@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Code/Code.spec.md

@@ -1,22 +1,20 @@
 ---
 schema_version: 3
-template_version: 6
+template_version: 7
 kind: component
 id: component:Code
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-27
 owners: [cixzhang]
 review_triggers: [public-api, behavior, theming, accessibility, visual]
 verified_by:
   [
+    .github/visual-baseline/manifest.json,
     packages/core/src/Code/Code.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/docPropLiterals.test.ts,
-    packages/core/src/docPropReferences.test.ts,
-    packages/cli/foundation/doc-compiler/inputs.test.mjs,
     .github/scripts/story-play-guard.js,
     apps/storybook/stories/Code.stories.tsx,
     apps/storybook/rtl-audit/verified-not-applicable.json,
@@ -31,7 +29,7 @@ architecture:
     architecture:component-test-sufficiency,
   ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-009]
 ---
 
 # Code component contract
@@ -43,12 +41,12 @@ system_specs: []
 | Public contract         | `Code` is exported from `@astryxdesign/core/Code`; it requires `children`, defaults `color` to `primary`, optionally accepts `secondary` or `inherit`, and accepts `size="inherit"`.                                                                    |
 | Behavior                | Code renders one semantic `<code>` element, uses the code type scale by default, and may inherit surrounding color or typography through explicit props.                                                                                                |
 | End-user impact         | Readers receive recognizable inline code that wraps instead of forcing its prose container wider.                                                                                                                                                       |
-| Builder impact          | Builders can discover the complete released API, use Code for short inline references, and use CodeBlock for standalone or multi-line snippets.                                                                                                         |
-| Compatibility/readiness | This audit restores missing consumer metadata and expands browser evidence. Runtime types, defaults, layout, and production component output are unchanged.                                                                                             |
+| Builder impact          | None; the record describes shipped behavior. Short inline references use Code; standalone or multi-line snippets use CodeBlock.                                                                                                                         |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                                                                                                                              |
 | Review checks           | Reject a non-`code` root, dropped content or root props, a ref that misses the root, a visual prop not reflected on the `code` target, undocumented released props/defaults, or a change that turns the inline component into a block-code replacement. |
 | Governing rules         | `architecture:public-component-api/INV1,INV5,INV6,INV8–INV9`; `architecture:component-theming-surface/INV3–INV7`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`.                                                                      |
 
-This table is a review projection; the body below is authoritative only after owner approval.
+This table is a review projection; the body below is authoritative.
 
 ## Intent
 
@@ -57,7 +55,7 @@ Present short technical references inside prose with native code semantics and a
 ## Compatibility and migration
 
 - Released default preserved: yes
-- Compatibility class: documentation and ownership restoration only; no runtime, type, default, style, target, or export change
+- Compatibility class: records shipped behavior; no runtime, type, default, style, target, or export change
 - Controlled/uncontrolled behavior: not applicable; Code owns no state
 - Migration decision: none
 
@@ -85,13 +83,13 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                          | Basis                                                                                   | Draft review state |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------ |
-| FR1 | Code MUST render one semantic `<code>` root containing the caller content.                                                                                                                   | shipped source, tests, docs, and HTML semantics                                         | verify             |
-| FR2 | Omitting `size` MUST use the code type-scale size; `size="inherit"` MUST inherit the surrounding font size and line height. `color` MUST select primary, secondary, or inherited text color. | shipped public types, source, tests, and stories                                        | verify             |
-| FR3 | Long inline content MUST remain wrap-capable, and Code MUST add only logical inline/block padding rather than physical-direction geometry.                                                   | shipped source and representative prose stories                                         | verify             |
-| FR4 | Supported DOM props, `className`, `style`, and `xstyle` MUST compose on the root, and the public ref MUST reach that root.                                                                   | `architecture:public-component-api/INV5,INV6,INV8`; shipped source and tests            | verify             |
-| FR5 | The painted root MUST retain the public `code` target and reflect the `color` visual axis. No internal target or separate state target is part of the shipped surface.                       | `architecture:component-theming-surface/INV3–INV7`; source and theming-target inventory | verify             |
+| ID  | Invariant                                                                                                                                                                                                                                                      | Basis                                                                           |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| FR1 | Code renders one semantic `<code>` root containing the caller content.                                                                                                                                                                                         | Shipped source, tests, docs, and HTML semantics                                 |
+| FR2 | The root uses the code font family and, when `size` is omitted, `--text-code-size` with the surrounding line height; `size="inherit"` also inherits the surrounding font size. `color` selects primary text (default), secondary text, or the inherited color. | Shipped public types, source, tests, and stories                                |
+| FR3 | The root paints `--color-background-muted` with `--radius-inner` corners and logical `--spacing-1` inline and `--spacing-0` block padding, and long inline content breaks to wrap rather than widening its prose container.                                    | Shipped source and representative prose stories                                 |
+| FR4 | Supported DOM props, `className`, `style`, and `xstyle` compose on the root, and the public ref reaches that root. The `code` target and `data-color` reflection apply after caller DOM props; `xstyle`, `className`, and `style` compose as ORD1 orders them. | `architecture:public-component-api/INV5,INV6,INV8`; shipped source and tests    |
+| FR5 | The painted root carries the public `code` target and reflects the `color` visual axis. No internal target or separate state target is part of the shipped surface.                                                                                            | `architecture:component-theming-surface/INV3–INV7`; source and target inventory |
 
 ### Allowed variation
 
@@ -129,7 +127,7 @@ Consumer migration instructions belong in consumer docs and release notes.
 | ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------ | ------------------ |
 | Container        | Distinguishes short technical text through code typography and compact background treatment. | observed shipped representation | inline technical content | FR1–FR5, AR1–AR2   |
 
-No current design record prescribes exact Code pixels. This observational draft records the shipped representation without promoting draft typography guidance.
+No current design record prescribes exact Code pixels; exact tuning stays in code and visual evidence.
 
 ### Theming anatomy
 
@@ -145,27 +143,27 @@ No current design record prescribes exact Code pixels. This observational draft
 
 - `architecture:public-component-api` owns export reachability, accepted root props, styling composition, ref reachability, released defaults, and consumer documentation.
 - `architecture:component-theming-surface` owns target qualification, target placement, visual-axis reflection, and metadata ownership.
-- `architecture:component-test-sufficiency` owns the rational evidence set and rejects component functional tests for documentation-only corrections when shared schema and projection checks are the capable layer.
+- `architecture:component-test-sufficiency` owns the rational evidence set.
 
 ## Verification map
 
-| Contract          | Verification                                                                                        | Representative states                                  | Mutation or failure expectation                                                                                                 | Audit section           |
-| ----------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1, AR1–AR2      | `Code.test.tsx`; semantic review of the Storybook fixtures                                          | default and prose composition                          | The root stops being a code element, content disappears, or the component invents interaction or accessible naming.             | `audit:Code/a11y`       |
-| FR2               | `Code.test.tsx`; `Colors` and `TextSizes` play assertions in the required Chromium story-play guard | primary, secondary, inherited color, inherited size    | A color choice stops reaching the target or inherited typography becomes visually indistinguishable from the fixed default.     | `audit:Code/behavior`   |
-| FR3               | `LongInlineContent` play assertion in the required Chromium story-play guard                        | constrained prose with an unbroken identifier          | Inline code forces physical-direction geometry or no longer wraps in constrained prose.                                         | `audit:Code/responsive` |
-| FR4               | `Code.test.tsx`; strict type/lint validation                                                        | ref plus supported styling and DOM passthrough         | The ref misses the root or supported consumer inputs stop composing on it.                                                      | `audit:Code/api`        |
-| FR5               | `themingTargets.test.ts`; Code consumer docs; source review                                         | every color value                                      | The target disappears or moves off the painter, color is no longer reflected, or metadata assigns the target to another owner.  | `audit:Code/theming`    |
-| RTL N/A           | `verified-not-applicable.json`                                                                      | every current story                                    | Directional glyph, physical inline placement, ordering, scrolling, overlay, or horizontal keyboard behavior appears unmeasured. | `audit:Code/rtl`        |
-| Consumer metadata | CLI `component Code --json`; docs typecheck; `docPropLiterals.test.ts`; `docPropReferences.test.ts` | required content, color values/default, inherited size | A released prop/default/target disappears from consumer discovery or docs name a value the source does not accept.              | `audit:Code/docs`       |
+| Contract           | Verification                                                                                                 | Representative states                                                  | Mutation or failure expectation                                                                                                                                                                                                                                                         | Audit section           |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| FR1, AR1, AR2      | `Code.test.tsx` render test                                                                                  | Default                                                                | A non-`code` root or missing content fails. Gap: the render test still passes when a wrapper becomes the root, and no test fails if Code adds a role, tab stop, or name, and no accessibility-tree check proves the exposed content (`spec:AST-009` FR3).                               | `audit:Code/a11y`       |
+| FR2, ORD2          | `Code.test.tsx` color tests; `Code.stories.tsx` `Colors` and `TextSizes` play checks in the story-play guard | Primary, secondary, inherited color; inherited size at four text sizes | A missing `data-color` reflection, secondary matching primary, inherited color or size not matching the parent, or every inherited size collapsing to one fails. Gap: the code font family and the default `--text-code-size` have no automated check beyond the visual baseline.       | `audit:Code/behavior`   |
+| FR3                | `Code.stories.tsx` `LongInlineContent` play check; stable visual baseline `core-code--default`               | Constrained prose with an unbroken identifier; default                 | Code that stops wrapping or widens its container fails the play check; a changed background, radius, or padding comes back changed for review. Gap: no unit test asserts the paint or padding.                                                                                          | `audit:Code/responsive` |
+| FR4, ORD1          | `Code.test.tsx` ref and passthrough tests                                                                    | Ref; `aria-label`, `className`, `style`, `xstyle`                      | A dropped ref, or a dropped caller prop, class, inline style, or `xstyle` class, fails. Gap: the ref test still passes when a wrapper receives the ref, and no test asserts that the target and `data-color` override caller DOM props or that caller `xstyle` follows the base styles. | `audit:Code/api`        |
+| FR5                | `themingTargets.test.ts`; `Code.test.tsx` color tests                                                        | Every color value                                                      | A missing target or `data-color` reflection fails.                                                                                                                                                                                                                                      | `audit:Code/theming`    |
+| RTL not applicable | `@astryx/no-physical-properties` lint rule; `apps/storybook/rtl-audit/verified-not-applicable.json` entry    | Every story                                                            | The lint rule fails a physical left/right property or value in Code's styles. Gap: no browser right-to-left check covers Code; the entry records the decision.                                                                                                                          | `audit:Code/rtl`        |
+| PR1                | Source review                                                                                                | Every state                                                            | Gap: no automated check fails if Code adds state, an effect, or a listener.                                                                                                                                                                                                             | `audit:Code/behavior`   |
 
 ## Decision log
 
-None. This audit restores missing consumer metadata and records shipped behavior; it makes no new product decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
-None. This observational draft does not decide exact visual tuning or broaden Code into a block-code component.
+None.
 
 ## Content boundary
 

package/src/CodeBlock/CodeBlock.doc.mjs

@@ -28,9 +28,9 @@ export const docs = {
     },
     {
       name: 'language',
-      type: 'string',
+      type: 'string | CodeLanguage',
       description:
-        'Language for syntax highlighting. Use "plaintext" to disable.',
+        'Language for syntax highlighting. A string selects a built-in: ts, js, tsx, jsx, json, html, xml, svg, css, scss, less, python, bash/sh/zsh/shell, php, hack, yaml, markdown, c, cpp (c++, cc, cxx, hpp, hh), sql, rust, kotlin, swift, go. Any other language is a value you import on its own and pass here: graphql, java, thrift, objectiveC, toml, powershell, ruby, lua, dockerfile from @astryxdesign/core/CodeBlock/languages/<path> (e.g. languages/graphql, languages/objective-c), or your own made with createCodeLanguage({name, identifiers, tokenize}). A value labels with its name and reflects its first identifier as data-language. Use "plaintext" to disable.',
       default: "'plaintext'",
     },
     {
@@ -74,6 +74,22 @@ export const docs = {
       type: '() => void',
       description: 'Callback after the code is copied.',
     },
+    {
+      name: 'endContent',
+      type: 'ReactNode',
+      description:
+        'Your own controls, shown just before Copy: in the header when the block has one, otherwise beside the code in the top inline-end corner, never over it. It never creates a header and never collapses the block. Ghost sm IconButtons match Copy’s size and variant.',
+      slotElements: [
+        {
+          __element: 'IconButton',
+          props: {
+            variant: 'ghost',
+            size: 'sm',
+            label: 'Run in terminal',
+          },
+        },
+      ],
+    },
     {
       name: 'isWrapped',
       type: 'boolean',
@@ -108,7 +124,8 @@ export const docs = {
     {
       name: 'tokenizer',
       type: '(code: string, language: string) => Array<{type: string; start: number; end: number}>',
-      description: 'Custom tokenizer override for unsupported languages.',
+      description:
+        'Deprecated: pass language={createCodeLanguage({name, identifiers, tokenize})} with this same function instead. Still works exactly as released and wins over the language; astryx upgrade rewrites static uses.',
     },
     {
       name: 'syntaxTheme',
@@ -230,7 +247,7 @@ export const docs = {
         name: 'Header Bar',
         required: false,
         description:
-          'Shows the title, visible language label, and copy button when a header is present. A title or visible language label creates the header; the copy button alone floats at the top-end of a headerless block.',
+          'Shows the title, visible language label, endContent, and copy button when a header is present. A title or visible language label creates the header at every line count. With no title and hasLanguageLabel={false}, endContent and the copy button sit in their own column beside the code, centred on the first line, and never cover it; a one-line block then reads as a single row.',
       },
       {
         name: 'Header Title',