@flowstack-ui/brick 0.1.11 → 0.1.12

package/dist/agents/em.json

@@ -0,0 +1,57 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "em",
+  "name": "Em",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Apply native stress emphasis while preserving the surrounding Brick typography and foreground.",
+  "useWhen": [
+    "Words in a sentence need semantic stress emphasis that changes the meaning or cadence when spoken."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "Text only needs an italic visual treatment without stress emphasis.",
+      "useInstead": "a deliberate application-owned visual recipe"
+    },
+    {
+      "condition": "Text needs importance rather than stress emphasis.",
+      "useInstead": "native strong inside the surrounding text owner"
+    }
+  ],
+  "composition": [
+    "Keep Em inside the Text, heading, link, or component content owner whose sentence it completes."
+  ],
+  "rules": [
+    {
+      "id": "em-native-semantics",
+      "level": "must",
+      "statement": "Use Em only for native stress emphasis and preserve its one em host; do not select it merely for italic paint."
+    },
+    {
+      "id": "em-inheritance",
+      "level": "must",
+      "statement": "Let Em inherit the surrounding typography and foreground rather than introducing a separate size, tone, or weight recipe."
+    },
+    {
+      "id": "em-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus em.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Em as a decorative italic label or replacing a sentence-level text owner with Em.",
+      "correction": "Keep Em inside meaningful surrounding copy and use it only when stress emphasis is semantically intended."
+    }
+  ],
+  "validation": [
+    "Confirm one native em element, inherited metrics and foreground, readable forced colors, normal selection and copy, and no tab stop or role.",
+    "Check nested sentence flow, localization, zoom, RTL, and CSS delivery."
+  ],
+  "related": [
+    "text",
+    "link",
+    "interface-composition"
+  ]
+}

package/dist/agents/em.md

@@ -0,0 +1,39 @@
+# Em agent guide
+
+## Purpose
+
+Apply native stress emphasis while preserving the surrounding Brick typography and foreground.
+
+## Use when
+
+- Words in a sentence need semantic stress emphasis that changes the meaning or cadence when spoken.
+
+## Choose something else when
+
+- Text only needs an italic visual treatment without stress emphasis. Use a deliberate application-owned visual recipe.
+- Text needs importance rather than stress emphasis. Use native strong inside the surrounding text owner.
+
+## Required composition
+
+- Keep Em inside the Text, heading, link, or component content owner whose sentence it completes.
+
+## Rules
+
+- **MUST:** Use Em only for native stress emphasis and preserve its one em host; do not select it merely for italic paint.
+- **MUST:** Let Em inherit the surrounding typography and foreground rather than introducing a separate size, tone, or weight recipe.
+- **MUST:** Load styles.css or core.css plus em.css.
+
+## Common mistakes
+
+- **Avoid:** Using Em as a decorative italic label or replacing a sentence-level text owner with Em. **Instead:** Keep Em inside meaningful surrounding copy and use it only when stress emphasis is semantically intended.
+
+## Validation checklist
+
+- Confirm one native em element, inherited metrics and foreground, readable forced colors, normal selection and copy, and no tab stop or role.
+- Check nested sentence flow, localization, zoom, RTL, and CSS delivery.
+
+## Related guidance
+
+- `text`
+- `link`
+- `interface-composition`

package/dist/agents/highlight.json

@@ -0,0 +1,73 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "highlight",
+  "name": "Highlight",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Discover literal queries in plain text through exact Atom behavior and render finished semantic match styling.",
+  "useWhen": [
+    "One plain text string needs deterministic visible query matches without recreating escaping, overlap, case, or whole-word behavior."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The relevant passage is already selected by the author.",
+      "useInstead": "Mark"
+    },
+    {
+      "condition": "Content is arbitrary React nodes or the application needs active result navigation.",
+      "useInstead": "application-owned rich-content traversal or search navigation"
+    }
+  ],
+  "composition": [
+    "Pass plain text through text and literal query values through query; keep surrounding sentence typography on Text or another content owner.",
+    "Let Highlight delegate all matching to Atom and keep search input, active result, counters, and navigation in the application."
+  ],
+  "rules": [
+    {
+      "id": "highlight-atom",
+      "level": "must",
+      "statement": "Use exact Atom Highlight behavior; do not copy or replace its segmentation, escaping, overlap, or exact-match logic."
+    },
+    {
+      "id": "highlight-plain-text",
+      "level": "must",
+      "statement": "Use Highlight only for plain text and literal queries, never by flattening or cloning arbitrary React content."
+    },
+    {
+      "id": "highlight-native",
+      "level": "must",
+      "statement": "Preserve Brick's fixed native span root and Atom-generated native mark matches."
+    },
+    {
+      "id": "highlight-recipes",
+      "level": "must",
+      "statement": "Select only the documented subtle, solid, or underline variant and accent or neutral tone."
+    },
+    {
+      "id": "highlight-state",
+      "level": "must",
+      "statement": "Keep search state, active-result navigation, counts, keyboard commands, and announcements outside Highlight."
+    },
+    {
+      "id": "highlight-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus highlight.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Using Mark or a consumer regular expression to discover query matches.",
+      "correction": "Pass the plain string and literal query to Highlight so exact Atom behavior owns segmentation."
+    }
+  ],
+  "validation": [
+    "Confirm literal, empty, repeated, overlapping, punctuation, Unicode, case-sensitive, whole-word, and first-match-only inputs preserve original text and copy order.",
+    "Confirm native span and mark output, closed recipes, forced colors, wrap, zoom, text spacing, localization, RTL, SSR, refs, and CSS delivery without focus or interaction."
+  ],
+  "related": [
+    "mark",
+    "text",
+    "interface-composition"
+  ]
+}

package/dist/agents/highlight.md

@@ -0,0 +1,43 @@
+# Highlight agent guide
+
+## Purpose
+
+Discover literal queries in plain text through exact Atom behavior and render finished semantic match styling.
+
+## Use when
+
+- One plain text string needs deterministic visible query matches without recreating escaping, overlap, case, or whole-word behavior.
+
+## Choose something else when
+
+- The relevant passage is already selected by the author. Use Mark.
+- Content is arbitrary React nodes or the application needs active result navigation. Use application-owned rich-content traversal or search navigation.
+
+## Required composition
+
+- Pass plain text through text and literal query values through query; keep surrounding sentence typography on Text or another content owner.
+- Let Highlight delegate all matching to Atom and keep search input, active result, counters, and navigation in the application.
+
+## Rules
+
+- **MUST:** Use exact Atom Highlight behavior; do not copy or replace its segmentation, escaping, overlap, or exact-match logic.
+- **MUST:** Use Highlight only for plain text and literal queries, never by flattening or cloning arbitrary React content.
+- **MUST:** Preserve Brick's fixed native span root and Atom-generated native mark matches.
+- **MUST:** Select only the documented subtle, solid, or underline variant and accent or neutral tone.
+- **MUST:** Keep search state, active-result navigation, counts, keyboard commands, and announcements outside Highlight.
+- **MUST:** Load styles.css or core.css plus highlight.css.
+
+## Common mistakes
+
+- **Avoid:** Using Mark or a consumer regular expression to discover query matches. **Instead:** Pass the plain string and literal query to Highlight so exact Atom behavior owns segmentation.
+
+## Validation checklist
+
+- Confirm literal, empty, repeated, overlapping, punctuation, Unicode, case-sensitive, whole-word, and first-match-only inputs preserve original text and copy order.
+- Confirm native span and mark output, closed recipes, forced colors, wrap, zoom, text spacing, localization, RTL, SSR, refs, and CSS delivery without focus or interaction.
+
+## Related guidance
+
+- `mark`
+- `text`
+- `interface-composition`

package/dist/agents/interface-composition.json

@@ -260,12 +260,12 @@
     },
     {
       "intent": "extended quotation and attribution",
-      "use": "native figure, blockquote, and figcaption with Brick text content",
-      "note": "Keep blockquote and figcaption as direct figure children when they form one self-contained unit, keep attribution outside the quoted content, and use cite only for the title of a referenced work.",
+      "use": "Blockquote",
+      "note": "Keep Content and Caption as siblings in Root, put the source URL on Content, and use Cite only for a referenced work or source.",
       "destinations": [
         {
-          "kind": "native-application",
-          "id": "native-quotation"
+          "kind": "component",
+          "id": "blockquote"
         },
         {
           "kind": "component",
@@ -341,9 +341,14 @@
       "statement": "Preserve document landmarks and semantic elements when Brick does not provide an owner; Brick-first is not permission to erase HTML meaning."
     },
     {
-      "id": "interface-native-quotation",
+      "id": "interface-blockquote",
+      "level": "must",
+      "statement": "For an extended quotation, use Blockquote and preserve its figure Root, blockquote Content, sibling figcaption Caption, source URL, and cited-work semantics."
+    },
+    {
+      "id": "interface-prose-trust",
       "level": "must",
-      "statement": "For an extended quotation, preserve native blockquote semantics and keep attribution outside the quoted content; when figure and figcaption associate the pair, keep blockquote and figcaption as direct figure children, use Brick content components inside them, and add narrow Block or application CSS only after supported composition cannot express the remaining relationship."
+      "statement": "Use Prose only after external content has been sanitized and parsed into trusted React children; keep heading hierarchy, landmarks, link destinations, media alternatives, table semantics, and trust policy application-owned."
     },
     {
       "id": "interface-responsive-navigation-data",
@@ -515,6 +520,8 @@
     "show",
     "hide",
     "accordion",
-    "list"
+    "list",
+    "blockquote",
+    "highlight"
   ]
 }

package/dist/agents/interface-composition.md

@@ -32,7 +32,7 @@ Build complete interfaces from Brick's structural, content, navigation, action,
 - **grouped application actions:** use Toolbar. Do not use AppBar.Toolbar as an ARIA toolbar.
 - **several related disclosure sections:** use Accordion. Preserve Header, Trigger, Content, and ContentInner ownership; use Collapsible for one disclosure.
 - **semantic item or sequence content:** use List. Use structured row parts only when needed and keep Trailing compact on narrow screens.
-- **extended quotation and attribution:** use native figure, blockquote, and figcaption with Brick text content. Keep blockquote and figcaption as direct figure children when they form one self-contained unit, keep attribution outside the quoted content, and use cite only for the title of a referenced work.
+- **extended quotation and attribution:** use Blockquote. Keep Content and Caption as siblings in Root, put the source URL on Content, and use Cite only for a referenced work or source.
 
 ## Rules
 
@@ -49,7 +49,8 @@ Build complete interfaces from Brick's structural, content, navigation, action,
 - **MUST:** Keep a real layout-item wrapper when it establishes flex or grid participation or the definite parent size required by ScrollArea, Carousel fill, or Image fill; asChild is not a wrapper-removal goal by itself.
 - **MUST:** Do not use Stack, Surface, Button, or another convenient component when a more specific Brick navigation, media, content, or interaction component owns the job.
 - **MUST:** Preserve document landmarks and semantic elements when Brick does not provide an owner; Brick-first is not permission to erase HTML meaning.
-- **MUST:** For an extended quotation, preserve native blockquote semantics and keep attribution outside the quoted content; when figure and figcaption associate the pair, keep blockquote and figcaption as direct figure children, use Brick content components inside them, and add narrow Block or application CSS only after supported composition cannot express the remaining relationship.
+- **MUST:** For an extended quotation, use Blockquote and preserve its figure Root, blockquote Content, sibling figcaption Caption, source URL, and cited-work semantics.
+- **MUST:** Use Prose only after external content has been sanitized and parsed into trusted React children; keep heading hierarchy, landmarks, link destinations, media alternatives, table semantics, and trust policy application-owned.
 - **MUST:** When desktop and mobile require distinct navigation components, share application-owned destination labels, hrefs, values, and ordering while preserving each pattern's correct Brick anatomy; do not duplicate navigation content or force one interaction tree across breakpoints.
 - **MUST:** Use Show and Hide for first-paint visibility; when a controlled interactive overlay may remain open across a breakpoint, synchronize its application state at that boundary so a hidden modal cannot retain focus, scroll lock, or isolation.
 - **SHOULD:** Express reusable brand values through semantic Brick tokens and a theme rather than repeating literal application values.
@@ -132,3 +133,5 @@ Emit this record for every native/framework fallback or direct stable-hook decla
 - `hide`
 - `accordion`
 - `list`
+- `blockquote`
+- `highlight`

package/dist/agents/kbd.json

@@ -0,0 +1,62 @@
+{
+  "schema": "flowstack.agent-component.v1",
+  "id": "kbd",
+  "name": "Kbd",
+  "package": "@flowstack-ui/brick",
+  "layer": "brick",
+  "kind": "component",
+  "purpose": "Render native keyboard-input notation with finished Brick sizing and visual recipes.",
+  "useWhen": [
+    "Copy needs to name a physical or virtual keyboard key or show a compact authored key sequence."
+  ],
+  "avoidWhen": [
+    {
+      "condition": "The application must register or execute a shortcut.",
+      "useInstead": "application-owned keyboard behavior"
+    },
+    {
+      "condition": "The content is a technical literal rather than keyboard input.",
+      "useInstead": "Code"
+    }
+  ],
+  "composition": [
+    "Keep Kbd inside meaningful surrounding copy or repeat Kbd for each authored key in a sequence with visible separators outside the key hosts."
+  ],
+  "rules": [
+    {
+      "id": "kbd-native",
+      "level": "must",
+      "statement": "Preserve the one native kbd host and use it only for keyboard-input notation."
+    },
+    {
+      "id": "kbd-passive",
+      "level": "must",
+      "statement": "Do not register shortcuts, listen for keys, translate platform labels, or add interaction inside Kbd."
+    },
+    {
+      "id": "kbd-recipes",
+      "level": "must",
+      "statement": "Select only the documented raised, outline, subtle, or plain variant and sm, md, or lg size."
+    },
+    {
+      "id": "kbd-css",
+      "level": "must",
+      "statement": "Load styles.css or core.css plus kbd.css."
+    }
+  ],
+  "commonMistakes": [
+    {
+      "mistake": "Putting an entire shortcut such as Ctrl+Shift+P inside one Kbd host without authored separation.",
+      "correction": "Use one Kbd per key and keep visible separators in the surrounding content owner."
+    }
+  ],
+  "validation": [
+    "Confirm native kbd semantics, closed recipes, readable key sequences, selection and copy, forced colors, zoom, localization, RTL, and CSS delivery.",
+    "Confirm Kbd adds no tab stop, role, shortcut listener, or platform detection."
+  ],
+  "related": [
+    "code",
+    "text",
+    "interface-composition"
+  ]
+}

package/dist/agents/kbd.md

@@ -0,0 +1,40 @@
+# Kbd agent guide
+
+## Purpose
+
+Render native keyboard-input notation with finished Brick sizing and visual recipes.
+
+## Use when
+
+- Copy needs to name a physical or virtual keyboard key or show a compact authored key sequence.
+
+## Choose something else when
+
+- The application must register or execute a shortcut. Use application-owned keyboard behavior.
+- The content is a technical literal rather than keyboard input. Use Code.
+
+## Required composition
+
+- Keep Kbd inside meaningful surrounding copy or repeat Kbd for each authored key in a sequence with visible separators outside the key hosts.
+
+## Rules
+
+- **MUST:** Preserve the one native kbd host and use it only for keyboard-input notation.
+- **MUST:** Do not register shortcuts, listen for keys, translate platform labels, or add interaction inside Kbd.
+- **MUST:** Select only the documented raised, outline, subtle, or plain variant and sm, md, or lg size.
+- **MUST:** Load styles.css or core.css plus kbd.css.
+
+## Common mistakes
+
+- **Avoid:** Putting an entire shortcut such as Ctrl+Shift+P inside one Kbd host without authored separation. **Instead:** Use one Kbd per key and keep visible separators in the surrounding content owner.
+
+## Validation checklist
+
+- Confirm native kbd semantics, closed recipes, readable key sequences, selection and copy, forced colors, zoom, localization, RTL, and CSS delivery.
+- Confirm Kbd adds no tab stop, role, shortcut listener, or platform detection.
+
+## Related guidance
+
+- `code`
+- `text`
+- `interface-composition`

package/dist/agents/layer-selection.json

@@ -36,14 +36,125 @@
         }
       ]
     },
+    {
+      "intent": "stress emphasis inside meaningful copy",
+      "use": "Em",
+      "note": "Keep Em inside the surrounding Text or component content owner and do not use it only for decorative italics.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "em"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "static authored relevance inside meaningful copy",
+      "use": "Mark",
+      "note": "Choose Highlight when a query must discover and segment matches; use Mark only when the author already knows the relevant passage.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "mark"
+        },
+        {
+          "kind": "component",
+          "id": "highlight"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "literal query matches inside one plain text string",
+      "use": "Highlight",
+      "note": "Pass plain text and literal queries to exact Atom-backed matching; keep rich-content traversal, search state, and active-result navigation in the application.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "highlight"
+        },
+        {
+          "kind": "component",
+          "id": "mark"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        }
+      ]
+    },
+    {
+      "intent": "trusted long-form React content with coherent descendant typography",
+      "use": "Prose",
+      "note": "Sanitize and parse external content before it reaches Prose; keep document semantics and trust policy in the application, and use direct Brick components for richer anatomy.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "prose"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        },
+        {
+          "kind": "component",
+          "id": "link"
+        },
+        {
+          "kind": "component",
+          "id": "list"
+        },
+        {
+          "kind": "component",
+          "id": "blockquote"
+        },
+        {
+          "kind": "component",
+          "id": "code-block"
+        },
+        {
+          "kind": "component",
+          "id": "table"
+        },
+        {
+          "kind": "component",
+          "id": "image"
+        }
+      ]
+    },
+    {
+      "intent": "keyboard-input notation inside meaningful copy",
+      "use": "Kbd",
+      "note": "Repeat one Kbd per authored key and keep visible separators outside; shortcut behavior and platform-label policy remain application-owned.",
+      "destinations": [
+        {
+          "kind": "component",
+          "id": "kbd"
+        },
+        {
+          "kind": "component",
+          "id": "text"
+        },
+        {
+          "kind": "component",
+          "id": "code"
+        }
+      ]
+    },
     {
       "intent": "extended quotation with visible attribution",
-      "use": "native blockquote with Brick text content",
-      "note": "Keep attribution outside blockquote; when the quotation and attribution form one self-contained unit, use native figure with direct blockquote and figcaption children. Cite names a referenced work, not the person quoted.",
+      "use": "Blockquote",
+      "note": "Keep Content and Caption as siblings in Root, put the source URL on Content, and use Cite for a referenced work or source rather than merely a person's name.",
       "destinations": [
         {
-          "kind": "native-application",
-          "id": "native-quotation"
+          "kind": "component",
+          "id": "blockquote"
         },
         {
           "kind": "component",
@@ -148,11 +259,15 @@
     {
       "intent": "preserved multi-line technical source",
       "use": "Code Block",
-      "note": "Keep syntax tokenization in a consumer adapter and pass the exact plain source separately for copy behavior.",
+      "note": "Keep syntax tokenization in a consumer adapter, pass the exact plain source separately for copy behavior, author line metadata explicitly, and use the bounded/collapse contract for long source.",
       "destinations": [
         {
           "kind": "component",
           "id": "code-block"
+        },
+        {
+          "kind": "component",
+          "id": "collapsible"
         }
       ]
     },
@@ -1233,6 +1348,11 @@
     "stack",
     "grid",
     "text",
+    "em",
+    "mark",
+    "highlight",
+    "kbd",
+    "blockquote",
     "image",
     "aspect-ratio",
     "code-block",

package/dist/agents/layer-selection.md

@@ -16,14 +16,19 @@ Choose the correct FLOWSTACK layer and require Brick-first composition when buil
 
 - **headings, paragraphs, captions, and eyebrows:** use Heading, Paragraph, Caption, or Eyebrow. Give Heading an explicit semantic level and choose its visual variant independently.
 - **other text with Brick typography:** use Text. Choose the semantic rendered element through its public API and author the intended letter case in content.
-- **extended quotation with visible attribution:** use native blockquote with Brick text content. Keep attribution outside blockquote; when the quotation and attribution form one self-contained unit, use native figure with direct blockquote and figcaption children. Cite names a referenced work, not the person quoted.
+- **stress emphasis inside meaningful copy:** use Em. Keep Em inside the surrounding Text or component content owner and do not use it only for decorative italics.
+- **static authored relevance inside meaningful copy:** use Mark. Choose Highlight when a query must discover and segment matches; use Mark only when the author already knows the relevant passage.
+- **literal query matches inside one plain text string:** use Highlight. Pass plain text and literal queries to exact Atom-backed matching; keep rich-content traversal, search state, and active-result navigation in the application.
+- **trusted long-form React content with coherent descendant typography:** use Prose. Sanitize and parse external content before it reaches Prose; keep document semantics and trust policy in the application, and use direct Brick components for richer anatomy.
+- **keyboard-input notation inside meaningful copy:** use Kbd. Repeat one Kbd per authored key and keep visible separators outside; shortcut behavior and platform-label policy remain application-owned.
+- **extended quotation with visible attribution:** use Blockquote. Keep Content and Caption as siblings in Root, put the source URL on Content, and use Cite for a referenced work or source rather than merely a person's name.
 - **one-dimensional alignment:** use Stack, HStack, or VStack. Use Grid for two-dimensional track relationships.
 - **bounded page width:** use Container. Use Surface or Card when the region also needs a visual boundary.
 - **top application or page bar:** use AppBar. Compose navigation and action components inside its sections.
 - **responsive presence:** use Show or Hide. Use CSS media visibility rather than rendering two JavaScript-controlled trees.
 - **image with resilient loading:** use Image. Use an adapter only when a framework image optimizer provides a measured capability Brick lacks.
 - **stable media or embed geometry before its content loads:** use AspectRatio. Choose Image when the asset owns resilient loading, Surface for a general visual boundary, and Skeleton for a temporary loading placeholder.
-- **preserved multi-line technical source:** use Code Block. Keep syntax tokenization in a consumer adapter and pass the exact plain source separately for copy behavior.
+- **preserved multi-line technical source:** use Code Block. Keep syntax tokenization in a consumer adapter, pass the exact plain source separately for copy behavior, author line metadata explicitly, and use the bounded/collapse contract for long source.
 - **navigation destination:** use Link or Button with href. Use Link for ordinary navigation and Button only for an emphasized destination.
 - **grouped disclosure sections:** use Accordion. Choose Collapsible for one independent disclosure and Tabs for one shared switching panel.
 - **ordinary blocking task, form, settings flow, or focused information:** use Dialog. Choose AlertDialog for one urgent consequential decision and Drawer when the temporary task belongs at a screen edge.
@@ -97,6 +102,11 @@ Choose the correct FLOWSTACK layer and require Brick-first composition when buil
 - `stack`
 - `grid`
 - `text`
+- `em`
+- `mark`
+- `highlight`
+- `kbd`
+- `blockquote`
 - `image`
 - `aspect-ratio`
 - `code-block`