surface-ui/surface

This system is a component library for building Phoenix LiveView interfaces, providing a declarative syntax and template engine that compiles to standard LiveView components. It includes a build tooling suite that generates CSS and JavaScript assets, along with a project initializer that scaffolds new Phoenix applications with Surface integration. The framework also features a catalogue system for documenting and testing components, alongside comprehensive compile-time validation and formatting utilities.

11 changes.

This period focused on a major API overhaul to align Surface with Phoenix LiveView, including the removal of legacy form and navigation components in favor of LiveView's native features. The library was restructured with a new compiler architecture, declarative component macros, and an extensible type handling system to improve compile-time validation and developer experience.

20 changes.

This period focused on the Surface 0.8 release, introducing a new compiler that generates CSS and JavaScript assets, alongside a dynamic component rendering system. The team also built out the Surface CLI with formatting, conversion, and project initialization tasks, supported by extensive test coverage for the compiler, formatter, and core components.

10 changes.

This period focused on restructuring the project initialization scaffolding into modular, reusable components to support granular feature configuration. Simultaneously, compile-time validation was introduced for Surface components, accompanied by extensive test coverage for both the new patcher system and component validation logic.

The Surface library now includes a formatter plugin that integrates with Elixir's built-in \mix format\ tool (available in Elixir 1.13+). This allows developers to format \.sface\ files and \\~F\ sigils automatically during standard formatting runs, eliminating the need to run \mix surface.format\ separately. The plugin supports configuration via \.formatter.exs\ to set line lengths for Surface code.

lib/surface/formatter · high confidence

The Surface library introduces a new \Surface.Catalogue\ system for documenting and testing components. This includes \Surface.Catalogue.Examples\ for stateless component demos, \Surface.Catalogue.LiveExample\ for interactive examples with state, and \Surface.Catalogue.Playground\ for interactive component sandboxes. These modules provide macros and utilities to generate catalogue entries, handle initial props/slots, and manage component data manipulation. The feature is currently marked as experimental.

lib/surface/catalogue · high confidence

The \surface.init\ template now includes a complete Tailwind CSS setup, featuring a new \layouts/app.sface\ and \layouts/root.sface\ that integrate with Phoenix 1.7's layout system. Additionally, a demo \Card\ component is generated with examples and a playground, providing users with a ready-to-use UI element styled with Tailwind classes.

priv · high confidence

The Surface compiler has been refactored into a dedicated module (Mix.Tasks.Compile.Surface) that automatically generates CSS and JavaScript/TypeScript assets during compilation. This includes extracting component styles into a single CSS file, bundling JS hooks, and generating Tailwind CSS variants based on component props and data attributes. The compiler now supports a :generate\_assets option to control asset generation, and allows customization of output paths for hooks, CSS, and variants via compiler options.

lib/mix/tasks/compile · high confidence

Surface now provides built-in \\<Component\>\ and \\<LiveComponent\>\ components under the \Surface.Components.Dynamic\ namespace. These allow users to dynamically inject regular and live components into templates by specifying a \module\ (and \function\ for regular components), enabling flexible, runtime-determined component rendering.

lib/surface/components/dynamic · high confidence

The Surface framework now uses a modular TypeHandler architecture to process attribute values. New modules have been added to lib/surface/type\_handler/ to handle specific types such as atoms, booleans, CSS classes, context operations, events, forms, hooks, keyword lists, maps, and styles. This change introduces a standardized interface for converting and validating attribute values at compile and runtime, replacing previous ad-hoc handling logic with a consistent, extensible structure.

_lib/surface/type\handler · high confidence

The \mix surface.init\ task now uses a new internal patching system to modify existing project files. This includes \ExPatcher\ for parsing and traversing Elixir source code using \Sourceror\, and \Patcher\ to apply a series of code patches to files. The \ProjectPatcher\ orchestrates the creation, deletion, and patching of project files, allowing the init task to safely update configuration files and templates.

lib/mix/tasks/surface/surface.init · high confidence

The Surface library introduces new directives to simplify attribute handling and debugging. The :props directive allows passing a map of props to a component, while :attrs and :values enable dynamic attribute generation for HTML tags. Additionally, the :debug directive can be used to print the component's AST or code during compilation for debugging purposes.

lib/surface/directive · high confidence

The Surface library now includes three new Mix tasks to streamline development workflows. \mix surface.format\ allows developers to format Surface \\~F\ sigils and \.sface\ files, supporting stdin input and standard formatter options. \mix surface.convert\ provides an automated migration tool to convert code from v0.7 to v0.8 syntax. Additionally, \mix surface.init\ configures a Phoenix project with Surface, offering options to enable features like Tailwind CSS, layouts, and catalogue integration.

lib/mix/tasks/surface · high confidence

The Surface compiler has been refactored to use a new modular architecture. A new \Surface.Compiler.Tokenizer\ handles the initial tokenization of template files, while a dedicated \Surface.Compiler.CSSParser\ and \Surface.Compiler.CSSTranslator\ manage CSS processing, including scoped CSS and deep selectors. The template parsing is now handled by \Surface.Compiler.Parser\ and \Surface.Compiler.ParseTreeTranslator\, which convert tokens into an AST. Additionally, \Surface.Compiler.EExEngine\ integrates the Surface AST with Phoenix's LiveView engine for rendering, and \Surface.Compiler.Converter\ manages the conversion of older template syntax (v0.8) to the new format.

lib/surface/compiler · high confidence

The \surface.init\ task's project patching logic has been refactored into distinct, modular components (catalogue, common, demo, docker, formatter, js\_hooks, layouts, scoped\_css, and tailwind). This restructuring allows for more granular control over which features are enabled during project generation, such as adding the \surface\_catalogue\ dependency and route, configuring \.sface\ file handling for formatters and live reload, setting up demo routes, and updating the Dockerfile build order. Users will see these specific configurations applied automatically when initializing a new Phoenix project with Surface.

_lib/mix/tasks/surface/surface.init/project\patchers · high confidence

The Surface library has been restructured to provide a more declarative way to build Phoenix LiveView components. The \\~F\ sigil is now used to translate Surface code into Phoenix templates, supporting stateless (\Surface.Component\), stateful (\Surface.LiveComponent\), and wrapper (\Surface.LiveView\) component types. A new \embed\_sface\ macro allows embedding \.sface\ templates as function components, and the library now includes a \Surface.Compiler\ for compiling templates. This change introduces new APIs and macros for defining and using components, enhancing the developer experience for building UIs with Surface.

lib · high confidence

The Surface library has been refactored to centralize public functions and component definitions. A new \Surface.API\ module provides the \prop\, \slot\, and \data\ macros for declaring component interfaces, while \Surface.BaseComponent\ and \Surface.MacroComponent\ define the foundational behaviors for all component types. This change introduces a structured AST system (\Surface.AST\) with dedicated nodes for containers, blocks, expressions, and directives, enabling more robust compile-time validation and error reporting via \Surface.CompileError\. Additionally, a \Surface.Catalogue\ behavior and helper modules (\Surface.IOHelper\, \Surface.TypeHandler\) are introduced to support component documentation, testing utilities, and type handling.

lib/surface · high confidence

The Surface compiler now validates component calls at compile time, surfacing warnings for missing required properties, unknown properties, and duplicate attributes or directives. Users will see specific error messages and hints during compilation, helping them catch issues before runtime.

lib/mix/tasks/compile/surface · high confidence

The Surface library has deprecated the \\<Context\>\, \\<Link\>\, \\<LivePatch\>\, and \\<LiveRedirect\>\ components, directing users to migrate to Phoenix LiveView's built-in \\<.link\>\ component and native context APIs. The \\<Raw\>\ component has been restored to ensure unprocessed content passes through to the template engine. These changes reflect a shift toward standardizing on LiveView's native features, with the deprecated components scheduled for removal in version 0.13.

lib/surface/components · high confidence

The application's configuration has been updated to use the modern \Config\ module instead of the deprecated \Mix.Config\ module. Additionally, a configuration for the \:phoenix\ application to use \Jason\ as the JSON library has been added specifically for the \:test\ environment.

config · high confidence

The \surface.init\ task's file patching logic has been reorganized into dedicated modules for each file type (component, config, formatter, JS, mix.exs, Phoenix, and text). This refactoring improves maintainability and allows for more precise, targeted modifications to generated project files, ensuring that updates to the template generation process are handled consistently across different file types.

_lib/mix/tasks/surface/surface.init/file\patchers · high confidence

The formatter has been refactored into a series of distinct phases (BlockExceptions, FinalNewline, Indent, Newlines, Render, SpacesToNewlines, and TagWhitespace) that process the AST sequentially. This change improves formatting consistency by handling indentation, newlines, and whitespace as separate, composable steps rather than a single monolithic pass. Users will see more predictable and consistent code formatting, particularly for block elements like \case\ and \if\, and the removal of the \\<\#template\>\ syntax in favor of \:slot\_name\ attributes.

lib/surface/formatter/phases · high confidence

This release introduces significant breaking changes to the Surface API to better align with Phoenix LiveView. The most notable change is the removal of all form-related components (including \\<Form\>\ and inputs) from the core library; they have been moved to a separate \surface\_form\_helpers\ project. Users must now use LiveView's built-in \\<.form\>\ component or the new \surface\_form\_helpers\ package. Additionally, the slot API has been updated to match LiveView's syntax (e.g., \\<\#slot {@name} /\>\), and the \Context\ API has been redesigned to improve diff-tracking and performance, with context propagation to slots now requiring explicit configuration. The \Surface.Catalogue.Example\ component was renamed to \Surface.Catalogue.LiveExample\ to distinguish stateful examples. The changelog and migration guide have been updated to reflect these changes.

(repo-wide) · high confidence

Add comprehensive compiler tests for Surface; Add comprehensive test suite for Surface's compile-time and runtime helpers; Add formatter plugin tests for Surface templates; Added comprehensive test coverage for Surface components; Added comprehensive test coverage for Surface components, compiler, and formatting; Added integration tests for Surface component change tracking; Added test coverage for Surface control structures; Added test fixtures for CSS scoping and variants; Added test fixtures for Surface component validation; Added test fixtures for Surface components and examples; Added test fixtures for component calls and external templates; Added test fixtures for the new catalogue system; Added test support infrastructure for Surface components; Added test templates for view rendering and nested views; Added tests for Surface Mix tasks; Added tests for Surface compile-time component validation; Added tests for Surface compiler asset generation and diagnostics; Added tests for Surface project initialization patchers; Added tests for dynamic components and LiveComponents; Added tests for surface.init patcher and integration scenarios; Added tests for the Surface Catalogue module.

The Surface library now requires Elixir 1.14 or higher and supports Phoenix LiveView versions 0.19.0, 0.20.10, or 1.0. Additionally, the \phoenix\_live\_view\ dependency has been changed from a git source to a hex package, and several development and test dependencies (such as \blend\, \floki\, and \ex\_doc\) have been updated or added.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 61 → 68 (+7.3)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 94 → 95 (+1.7)
• Architecture 97 → 95 (-1.7)
• Maturity 54 → 54 (+0.1)
• Readiness 50 → 66 (+16.8)
• Security 82 → 96 (+14.1)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — no supported dependency manifest was read
• Duplicated block (13 lines × 6) (lib/surface/compiler/eex_engine.ex)
• Duplicated block (14 lines × 2) (lib/surface/catalogue/examples.ex)
• Duplicated block (16 lines × 2) (lib/mix/tasks/surface/surface.init/file_patchers/component.ex)
• Duplicated block (5 lines × 2) (lib/surface/compiler/eex_engine.ex)
• Duplicated block (6 lines × 2) (lib/surface/compiler/css_tokenizer.ex)
• Duplicated block (6 lines × 2) (lib/surface/compiler/parse_tree_translator.ex)
• Duplicated block (7 lines × 2) (lib/surface/compiler/eex_engine.ex)
• Duplicated block (7 lines × 2) (lib/surface/compiler/parser.ex)
• Duplicated block (8 lines × 2) (lib/surface/compiler/tokenizer.ex)
• FileTooLong: surface/ast.ex (lib/surface/ast.ex)
• High CVE: [GHSA redacted] (mix.lock)
• High CVE: [GHSA redacted] (mix.lock)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• No exposed public API
• Off-boarding risk: anonymized user #1
• Test reliability not included
• …and 4 more

• Documentation: no installation or build instructions (README.md)
• Duplicated block (13 lines × 3) (lib/surface/catalogue/examples.ex)
• Duplicated block (14 lines × 6) (lib/surface/compiler/eex_engine.ex)
• Duplicated block (15 lines × 2) (lib/mix/tasks/surface/surface.init/file_patchers/component.ex)
• Duplicated block (3–18 lines × 3) (lib/surface/compiler/eex_engine.ex)
• Duplicated block (5 lines × 2) (lib/mix/tasks/surface/surface.init/file_patchers/mix_exs.ex)
• Duplicated block (6 lines × 2) (lib/surface/compiler/parse_tree_translator.ex)
• Duplicated block (7 lines × 2) (lib/surface/compiler/eex_engine.ex)
• Duplicated block (7 lines × 2) (lib/surface/compiler/eex_engine.ex)
• Duplicated block (7 lines × 2) (lib/surface/compiler/parser.ex)
• Duplicated block (8 lines × 2) (lib/mix/tasks/surface/surface.convert.ex)
• Duplicated block (8 lines × 2) (lib/surface/compiler/tokenizer.ex)
• High CVE: [GHSA redacted] (mix.lock)
• High CVE: [GHSA redacted] (mix.lock)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Members sharing a duplicated core (6 members, 50+ identical tokens) (lib/surface/compiler/eex_engine.ex)
• No dependency advisory monitoring
• …and 35 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

surface-ui/surface was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.