{
  "version": "0.6.4",
  "components": [
    {
      "slug": "stage-card",
      "name": "Stage card",
      "summary": "Highlight the next useful task for the current merchant stage.",
      "props": [
        [
          "title",
          "string",
          "Required",
          "Clear action-oriented heading."
        ],
        [
          "description",
          "string",
          "Required",
          "Explain the outcome."
        ],
        [
          "featured",
          "boolean",
          "false",
          "Span the primary bento area."
        ],
        [
          "eyebrow",
          "string",
          "—",
          "Stage or real count."
        ],
        [
          "action",
          "ReactNode",
          "—",
          "Native s-button or s-link."
        ],
        [
          "kind",
          "string",
          "companies",
          "import or companies artwork."
        ]
      ],
      "example": "<StageCard featured title=\"Group your customers\" description=\"Review company and location suggestions.\" action={<s-button variant=\"primary\">Find customers</s-button>} />",
      "guidelines": "Use one featured action. Stage must come from real store/task state. Avoid a wall of equal cards.",
      "accessibility": "Static artwork is decorative; heading and action communicate the same purpose.",
      "version": "0.1.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "bento-grid",
      "name": "Bento grid",
      "summary": "Arrange an uneven, responsive set of task cards.",
      "props": [
        [
          "children",
          "ReactNode",
          "Required",
          "StageCard children; one featured item."
        ]
      ],
      "example": "<BentoGrid><StageCard featured {...primary} /><StageCard {...secondary} /></BentoGrid>",
      "guidelines": "Start with the primary journey, then secondary tasks. At mobile widths cards return to a linear reading order.",
      "accessibility": "DOM order is reading and tab order. Do not use visual reordering to change task priority.",
      "version": "0.1.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "empty-state",
      "name": "Empty state",
      "summary": "Explain missing data and offer one useful next action.",
      "props": [
        [
          "title",
          "string",
          "Required",
          "Describe what will appear."
        ],
        [
          "description",
          "string",
          "Required",
          "Explain the next step or why a search is empty."
        ],
        [
          "action",
          "ReactNode",
          "—",
          "Native primary action."
        ],
        [
          "kind",
          "string",
          "companies",
          "companies or tasks artwork."
        ]
      ],
      "example": "<EmptyState title=\"Your companies will appear here\" description=\"Find customers to prepare your first company.\" action={<s-button href=\"/migration\">Find customers</s-button>} />",
      "guidelines": "Use after a successful empty read. Show loading and errors separately. Do not imply a failed request means zero records.",
      "accessibility": "Decorative SVG is hidden from assistive technology; the section has an accessible title.",
      "version": "0.1.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "source-tabs",
      "name": "Source tabs",
      "summary": "Switch related source or presentation modes with accessible tabs.",
      "props": [
        [
          "items",
          "{id,label}[]",
          "Required",
          "Stable IDs and human labels."
        ],
        [
          "selected",
          "string",
          "Required",
          "Controlled active item."
        ],
        [
          "onSelect",
          "(id)=>void",
          "Required",
          "Update host state."
        ],
        [
          "children",
          "ReactNode",
          "—",
          "Current panel content."
        ],
        [
          "label",
          "string",
          "Views",
          "Accessible tab-list name."
        ]
      ],
      "example": "<SourceTabs items={[{id:\"search\",label:\"Search & filter\"},{id:\"file\",label:\"Upload file\"}]} selected={source} onSelect={setSource}>{panel}</SourceTabs>",
      "guidelines": "Search/filter is the default customer source. Switching the tab must not silently discard an imported file or selected customers.",
      "accessibility": "Left/right arrows, Home/End, roving tabIndex, aria-selected and linked tab/panel IDs.",
      "version": "0.1.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "filter-builder",
      "name": "Filter builder",
      "summary": "Build bounded AND/OR expressions from a host-provided field schema.",
      "props": [
        [
          "expression",
          "FilterExpression",
          "—",
          "Nested group/rule AST; all, any, none, exactly one."
        ],
        [
          "onExpressionChange",
          "(expression)=>void",
          "—",
          "Controlled AST callback."
        ],
        [
          "groups",
          "FilterGroup[]",
          "Required",
          "OR groups containing AND rules."
        ],
        [
          "fields",
          "FilterField[]",
          "Required",
          "Allowed fields, operators, optional choices and placeholders."
        ],
        [
          "onChange",
          "(groups)=>void",
          "Required",
          "Controlled expression update."
        ]
      ],
      "example": "<FilterBuilder groups={groups} fields={fields} onChange={setGroups} />",
      "guidelines": "Use expression for nested AND/OR/NOT/exactly-one logic. groups/onChange remain v1-compatible. Field suggestions allow free manual entry and never replace other rules. Hosts validate depth, allowlists, query semantics and scan budgets on the server.",
      "accessibility": "Native labeled fields and selects; accessible value-picker buttons and popover; keyboard-usable nested groups.",
      "version": "0.2.1",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "settings-layout",
      "name": "Settings layout",
      "summary": "Compose settings into an anchored side navigation and native sections.",
      "props": [
        [
          "sections",
          "{id,title,children}[]",
          "Required",
          "Stable unique section IDs; native controls."
        ]
      ],
      "example": "<SettingsLayout sections={[{id:\"connection\",title:\"Store connection\",children:<ConnectionSettings/>}]} />",
      "guidelines": "Use native sections and controls. Explain only settings the merchant can act on. Navigation stays sticky on desktop and becomes a horizontal list on small screens.",
      "accessibility": "Anchor links work without scripting. IntersectionObserver updates aria-current without moving keyboard focus.",
      "version": "0.1.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "resource-toolbar",
      "name": "Resource toolbar",
      "summary": "Keep a compact view selector beside a flexible native search input.",
      "props": [
        [
          "children",
          "ReactNode",
          "Required",
          "Native select, search field and action buttons."
        ]
      ],
      "example": "<ResourceToolbar><s-select label=\"View\"/><s-text-field label=\"Search\"/><s-button>Columns</s-button></ResourceToolbar>",
      "guidelines": "The view selector is 128px, search fills the remaining width. Do not stretch an All selector across half the table. Wrap at narrow sizes. Use a 3:7 view/search ratio and separate sort and column controls.",
      "accessibility": "Host supplies meaningful labels. DOM order stays identical to visual order.",
      "version": "0.5.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "brand-footer",
      "name": "Brand footer",
      "summary": "Use a consistent attribution link across Kaupvik products.",
      "props": [
        [
          "children",
          "ReactNode",
          "—",
          "Optional concise product note."
        ],
        [
          "href",
          "string",
          "https://kaupvik.com",
          "Public studio URL."
        ]
      ],
      "example": "<BrandFooter>Existing customer identities are preserved.</BrandFooter>",
      "guidelines": "Use the real clickable Kaupvik link. Keep attribution separate from primary merchant tasks.",
      "accessibility": "Native s-link opens the public studio in a new tab with noopener/noreferrer.",
      "version": "0.1.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "relationship-graph",
      "name": "Relationship graph",
      "summary": "Explore real companies, purchasing locations and shared buyers.",
      "props": [
        [
          "nodes",
          "Node[]",
          "Required",
          "Stable native GIDs, business node data, parentId and the host-computed position."
        ],
        [
          "edges",
          "Edge[]",
          "Required",
          "Verified native relationship and role labels."
        ],
        [
          "onSelect",
          "(id)=>void",
          "—",
          "Inspect a record in the host."
        ],
        [
          "label",
          "string",
          "Company relationships",
          "Accessible graph name."
        ],
        [
          "onMoveRequest",
          "(buyerId,locationId)=>void",
          "—",
          "Optional drop intent; host previews and authorizes."
        ],
        [
          "focusId",
          "string",
          "—",
          "Centre this card when it changes, e.g. a new record."
        ],
        [
          "fitToken",
          "string|number",
          "—",
          "Change it to refit the camera; a local card collapse never refits."
        ],
        [
          "onReorder",
          "(id,targetId)=>void",
          "—",
          "Sibling dragged next to target; host saves order."
        ],
        [
          "tools",
          "CanvasTool[]",
          "[]",
          "Extra toolbar controls such as linked expand/collapse per level."
        ],
        [
          "initialLayout",
          "{viewport}",
          "—",
          "Saved camera only; coordinates are never persisted."
        ],
        [
          "onLayoutChange",
          "(layout)=>void",
          "—",
          "Host debounces revisioned camera persistence."
        ]
      ],
      "example": "import {RelationshipGraph} from '@kaupvik/polaris/graph';\nimport '@xyflow/react/dist/style.css';\n<RelationshipGraph nodes={nodes} edges={edges} onSelect={setSelected} />",
      "guidelines": "The host owns the tidy layout: it computes every card position from the tree and saved sibling order, so the canvas stores no coordinates and always renders an even, layered map. Dragging a card returns it to the computed position and only emits onReorder for siblings; it does not nudge a card pixel by pixel. Canvas tools receive pressed state for level filters (locations, buyers) and expand/collapse-all actions. Collapse never fits or recenters the viewport. Hand/select tools support Shift multi-selection. Native relationship drops emit reviewed intent only. Empty app draft profiles can appear before assigning native companies. Toolbar icon and label share one centred inline-flex line. Card icons keep a fixed 20px box so a glyph never hangs below its label, and connection handles stay invisible because the add control is drawn at the same anchor. Hand pans and zooms and still opens a card on click; only Select lets a drag reorder, so a pan gesture cannot move the tree. The camera refits only when the host changes fitToken (its global expand/collapse actions) or on first render, so collapsing one card keeps the merchant's local view; bounds come from the host layout.",
      "accessibility": "React Flow keyboard navigation and controls; always provide a tree/list alternative and a native-record inspector. Respect reduced motion; do not animate relationship edges.",
      "version": "0.6.4",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "skeleton",
      "name": "Skeleton",
      "summary": "Reserve the expected content geometry while data is loading.",
      "props": [
        [
          "variant",
          "page | card | table | graph | form",
          "card",
          "Expected layout."
        ],
        [
          "rows / columns",
          "number",
          "4 / 1",
          "Match incoming content."
        ],
        [
          "minHeight",
          "number",
          "Variant default",
          "Reserved region height."
        ],
        [
          "label",
          "string",
          "Loading content",
          "Accessible status name."
        ]
      ],
      "example": "<Skeleton variant=\"table\" rows={6} columns={3} />",
      "guidelines": "Use for pending real requests. Preserve data during refresh. Loading, errors and successful empty results are different states.",
      "accessibility": "Labeled status with aria-busy; shimmer respects reduced motion.",
      "version": "0.2.1",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "wizard-steps",
      "name": "Wizard steps",
      "summary": "Guide a source-specific flow with one current step.",
      "props": [
        [
          "steps",
          "string[]",
          "Required",
          "Ordered source-specific labels."
        ],
        [
          "current",
          "number",
          "Required",
          "Zero-based active step."
        ],
        [
          "onSelect",
          "(index)=>void",
          "—",
          "Return to earlier input steps."
        ]
      ],
      "example": "<WizardSteps steps={[\"Choose customers\",\"Group\",\"Review\",\"Create profiles\",\"Verify\"]} current={step} onSelect={setStep} />",
      "guidelines": "Use one primary action per step. Preserve input on back. Native search skips file mapping. Never let navigation skip business confirmation.",
      "accessibility": "Ordered navigation, aria-current=step, focusable earlier steps; future steps disabled.",
      "version": "0.2.1",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "settings-row",
      "name": "Settings row",
      "summary": "Separate settings with right-aligned actions.",
      "props": [
        [
          "title",
          "string",
          "Required",
          "Setting or destination."
        ],
        [
          "description",
          "string",
          "—",
          "Supporting explanation."
        ],
        [
          "icon",
          "Polaris icon name",
          "—",
          "Official s-icon."
        ],
        [
          "action",
          "ReactNode",
          "—",
          "One clear native action."
        ]
      ],
      "example": "<SettingsRow title=\"Catalogs\" icon=\"catalog-product\" action={<s-button>Open</s-button>} />",
      "guidelines": "Keep description on the left, action on the right, and a subtle divider between rows.",
      "accessibility": "Reading order follows title, description, action. Decorative icon supplements text. Narrow layouts wrap.",
      "version": "0.2.1",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "mapping-table",
      "name": "Mapping table",
      "summary": "Review field mapping in small categories and source examples.",
      "props": [
        [
          "groups",
          "{title,icon,fields}[]",
          "Required",
          "Roughly 5–7 related fields per category."
        ],
        [
          "fields",
          "Record<string,string>",
          "Required",
          "Destination IDs and labels."
        ],
        [
          "columns",
          "string[]",
          "Required",
          "Real uploaded headers."
        ],
        [
          "mapping",
          "Record<string,string>",
          "Required",
          "Controlled assignments."
        ],
        [
          "examples",
          "Record<string,unknown>",
          "—",
          "First actual source row."
        ],
        [
          "onChange",
          "(mapping)=>void",
          "Required",
          "Updates source only."
        ]
      ],
      "example": "<MappingTable groups={fieldGroups} fields={fields} columns={headers} mapping={mapping} examples={sourceRow} onChange={setMapping} />",
      "guidelines": "Review categories through disclosure. Show destination, source column and a real example. Mapping never writes native business records. Use native chevron and arrow icons in fixed, centered columns. Preserve the source-to-field alignment when categories expand.",
      "accessibility": "Native disclosure and labeled selects. Logical keyboard order; examples hide on narrow screens.",
      "version": "0.2.1",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "choice-switch",
      "name": "Choice switch",
      "summary": "Choose a compact horizontal preset without nested button surfaces.",
      "props": [
        [
          "items",
          "{id,label}[]",
          "Required",
          "Stable alternatives."
        ],
        [
          "selected",
          "string",
          "Required",
          "Active ID; empty means manual conditions."
        ],
        [
          "onSelect",
          "(id)=>void",
          "Required",
          "Host replaces conditions."
        ],
        [
          "label",
          "string",
          "Quick filters",
          "Accessible group name."
        ]
      ],
      "example": "<ChoiceSwitch label=\"Quick filters\" items={[{id:\"wholesale\",label:\"Wholesale\"},{id:\"unassigned\",label:\"Without a company\"}]} selected={preset} onSelect={setPreset} />",
      "guidelines": "Exclusive horizontal presets with one HTML button surface, native check icons and aria-pressed semantics. Native s-press-button exposes secondary/tertiary only, so this Kaupvik pattern provides the requested dark selected surface with white text. Arrow/Home/End switch and focus; host clears selection after manual filter edits. Keep one consistent pill radius and no nested frame.",
      "accessibility": "Native button pressed state; arrow keys, Home and End move focus and selection. Space/Enter activate. Each option remains natively keyboard accessible; selection is also shown by a native check icon. Wrap on narrow screens.",
      "version": "0.5.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "task-progress",
      "name": "Task progress",
      "summary": "Show real work and verification as separate, honest progress stages.",
      "props": [
        [
          "stages",
          "{id,label,completed,total}[]",
          "Required",
          "Actual saved operation and verification counts."
        ],
        [
          "label",
          "string",
          "Task progress",
          "Accessible region description."
        ]
      ],
      "example": "<TaskProgress stages={[{id:\"import\",label:\"Import profiles\",completed:6,total:6},{id:\"verify\",label:\"Verify access\",completed:0,total:2}]} />",
      "guidelines": "Native s-progress adapter with separate actual saved-operation and native-verification stages. Runtime and installed Polaris 2 types verify these native controls. Do not estimate time or advance with a timer; completed operations do not imply access verification. Native atoms own track, fill, semantics and tone.",
      "accessibility": "Each native progress exposes a label and actual numeric counts. Completion includes a native check icon. Native reduced-motion behavior is retained.",
      "version": "0.3.1",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    },
    {
      "slug": "side-drawer",
      "name": "Side drawer",
      "summary": "Review and confirm a staged form in a rounded adaptive side panel.",
      "props": [
        [
          "title",
          "string",
          "Required",
          "Dialog heading."
        ],
        [
          "description",
          "string",
          "—",
          "Purpose and draft boundary."
        ],
        [
          "children",
          "ReactNode",
          "Required",
          "Native form controls."
        ],
        [
          "actions",
          "ReactNode",
          "Required",
          "Cancel and confirm native buttons."
        ],
        [
          "onClose",
          "()=>void",
          "Required",
          "Discard unconfirmed draft."
        ],
        [
          "surfaceSelector",
          "string",
          "[data-kp-drawer-surface]",
          "Host content to resize."
        ]
      ],
      "example": "<SideDrawer title=\"Review & edit row\" onClose={close} actions={<><s-button onClick={close}>Cancel</s-button><s-button variant=\"primary\" onClick={save}>Confirm changes</s-button></>}><s-text-field label=\"Company name\" /></SideDrawer>",
      "guidelines": "Kaupvik composition using the native HTML dialog focus boundary and Shopify form controls. Desktop reserves dock width; narrow screens use a modal panel. Host owns staged values and must commit only on confirm. Host coordinates other fixed launchers while open; conversation state remains owned by Harbor. Never call business APIs from this shell.",
      "accessibility": "Native modal focus trap, Escape cancellation, titled/described dialog and focus return. Closing must be equivalent to Cancel. Mobile backdrop, overflow scrolling, reduced motion and minimum target sizes are preserved.",
      "version": "0.3.0",
      "status": "Available",
      "owner": "Kaupvik UI foundation"
    }
  ]
}
