@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-mystique-builder/components/fc.reports.ipuipc.md

@@ -0,0 +1,54 @@
+---
+alias: "fc.reports.ipuipc"
+aliases:
+  - fc.reports.ipuipc
+category: content
+module: Analytics
+---
+# fc.reports.ipuipc
+
+IPU (Inventory Position Update) and IPC (Inventory Position Change) reporting component with line chart visualization, configurable filters for report type, date range, and granularity.
+
+## When to Use
+- Inventory analytics dashboards
+- Monitoring inventory update volumes over time
+- Capacity planning and IPU/IPC usage tracking
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `width` | CardWidth | No | Card width on 12-column grid. Named widths: `"quarter"`, `"third"`, `"half"`, `"two-thirds"`, `"full"`, or number `1-12`. Default: `"full"`. Mobile auto-adjusts to 12. |
+
+## Data Binding
+The component self-manages its data fetching based on three user-configurable filters:
+
+- **Display**: Report type -- "Inventory Position Update" (default) or "Inventory Position Change"
+- **Date/time range**: Visualization period, default last 31 days. Based on UTC time.
+- **Granularity**: Detail level -- "Minute", "Hour", or "Day" (default)
+
+The line chart displays data points across the selected date range. X-axis shows the date range (UTC), Y-axis shows quantity of inventory updates. A "Total Updates" summary shows the cumulative sum of all usages within the selected range.
+
+## Descendants
+No.
+
+## Gotchas
+- Data older than 185 days cannot be displayed. Exceeding this limit shows: "The maximum time frame is 185 days."
+- Granularity constrains the date range: Minute granularity max 12 hours, Hour granularity max 31 days. Day granularity has no additional constraint beyond 185 days.
+- Mismatched granularity/range shows: "The time frame for your chosen granularity is too long."
+- Both chart start and end points use UTC timestamps.
+
+## Manifest Example
+```json
+{
+  "component": "fc.reports.ipuipc",
+  "props": {
+    "width": "full"
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.return.rowExpansion.md

@@ -0,0 +1,19 @@
+---
+alias: "fc.return.rowExpansion"
+aliases:
+  - fc.return.rowExpansion
+category: content
+module: Returns
+---
+# fc.return.rowExpansion
+
+Expandable detail row for return items in a list.
+
+## When to Use
+- Return list page — expand to see item details
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.scanner.barcode.md

@@ -0,0 +1,21 @@
+---
+alias: "fc.scanner.barcode"
+aliases:
+  - fc.scanner.barcode
+  - fc.barcode.scanner
+category: content
+module: Core
+---
+# fc.scanner.barcode
+
+USB barcode scanner input field for warehouse operations.
+
+## When to Use
+- Warehouse pick/pack barcode scanning
+- Desktop scanner hardware integration
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.scanner.barcodeFilter.md

@@ -0,0 +1,72 @@
+---
+alias: "fc.scanner.barcodeFilter"
+aliases:
+  - fc.scanner.barcodeFilter
+category: content
+module: Core
+---
+
+# fc.scanner.barcodeFilter
+
+Combined barcode scanner and text filter component that renders a sticky filter bar with hardware barcode scanner support, text input filtering, and optional camera scanner integration.
+
+## When to Use
+- Add barcode scanning and text filtering above a list (pick, pack, count workflows)
+- Enable hardware barcode scanner input on store/warehouse pages
+- Provide a combined scan + filter experience with match count display
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `onFilter` | `(value: string) => void` | Yes* | Callback when the text filter value changes |
+| `onScan` | `(value: string) => boolean \| undefined` | Yes* | Callback when a barcode is scanned. Return `true` to indicate a match. |
+| `setValue` | `(value: string) => void` | Yes* | Setter for the filter input value |
+| `value` | string | No | Current filter input value |
+| `debounceTimeout` | number | No | Debounce timeout for hardware scanner input (ms) |
+| `placeholderText` | string[] | No | i18n key array for the filter placeholder text. Default: `["fc.barcodeFilter.placeholder", "Filter results"]` |
+| `showingText` | string[] | No | i18n key array for the match count text. Supports `{{currentCount}}` and `{{totalCount}}` template vars. Default: `["fc.barcodeFilter.list.count", "Showing {{currentCount}} of {{totalCount}} items"]` |
+| `currentCount` | number | No | Current number of filtered/matching items |
+| `totalCount` | number | No | Total number of items before filtering |
+| `enableCameraScanner` | boolean | No | Enable the camera scanner button on mobile devices (opens `fc.scanner.camera`) |
+| `camera` | object | No | Camera configuration props passed to `fc.scanner.camera` |
+
+*These callbacks are typically provided by the parent `fc.quantity.list` or a custom wrapper, not directly in manifest JSON.
+
+## Data Binding
+This component does not consume data directly. It provides filter/scan callbacks that the parent list component uses to filter its data.
+
+## Descendants
+No -- self-contained filter/scanner component.
+
+## Composition Patterns
+- `fc.quantity.list` automatically renders `fc.scanner.barcodeFilter` when `scannerProps` is provided
+- Can be used standalone above any list via programmatic integration
+- Integrates with `fc.scanner.camera` on mobile for camera-based barcode scanning
+
+## Gotchas
+- If any of `onFilter`, `onScan`, or `setValue` are missing, the component renders nothing (returns `null`).
+- The filter bar is sticky (`position: sticky`, `top: -21px`) and floats above the list content as the user scrolls.
+- Hardware barcode scanner detection is handled by `SimpleScanner` (a hidden input that captures rapid keystrokes).
+- The camera scanner button only appears on mobile devices (`isMobile` from `react-device-detect`) and only when `enableCameraScanner` is `true`.
+- When active, the filter bar shows a count indicator (e.g. "Showing 3 of 15 items") styled as a secondary-colored banner.
+- When stuck to the top (scrolled), the card changes to square corners with elevation 3 and wider width to span the page.
+- Registered with category `content` in the component registry.
+
+## Manifest Example
+```json
+{
+  "component": "fc.scanner.barcodeFilter",
+  "props": {
+    "placeholderText": ["fc.barcodeFilter.placeholder", "Scan or type to filter..."],
+    "showingText": ["fc.barcodeFilter.list.count", "Showing {{currentCount}} of {{totalCount}} items"],
+    "enableCameraScanner": true,
+    "debounceTimeout": 300
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.scanner.camera.md

@@ -0,0 +1,20 @@
+---
+alias: "fc.scanner.camera"
+aliases:
+  - fc.scanner.camera
+category: content
+module: Core
+---
+# fc.scanner.camera
+
+Mobile camera barcode scanner using device camera API.
+
+## When to Use
+- Mobile warehouse/store scanning
+- Camera-based barcode input on tablets/phones
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.settingForm.md

@@ -0,0 +1,64 @@
+---
+alias: "fc.settingForm"
+aliases:
+  - fc.settingForm
+category: content
+module: Core
+---
+# fc.settingForm
+
+Form for creating and updating Fluent Commerce settings. Renders fields based on a schema definition and the setting's current value. Supports create (override default) and update operations.
+
+## When to Use
+- Settings editor pages
+- Retailer/account/location configuration forms
+- Any page where a user needs to view and edit a Fluent setting value
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `setting` | string | **Yes** | Setting name to load and edit (e.g., `"orderWorkflowConfig"`) |
+| `schema` | string | **Yes** | Schema setting name that defines the form field structure |
+| `context` | string | **Yes** | Setting context: `"ACCOUNT"`, `"RETAILER"`, or `"AGENT"` (location) |
+| `contextId` | number / string | Recommended | Context ID (retailer ID, account ID, or location ID). Supports template strings: `"{{activeRetailer.id}}"`, `"{{params.id}}"` |
+| `title` | string | No | Card header title (inherited from Card) |
+| `width` | CardWidth | No | Card width (inherited from Card) |
+| `highlight` | string | No | Card border highlight color (inherited from Card) |
+
+## Data Binding
+`contextId` supports template strings with access to `{{activeContext.id}}`, `{{activeLocation.id}}`, `{{activeRetailer.id}}`, `{{activeUser}}`, and `{{params.*}}` (route params).
+
+## Descendants
+No.
+
+## Gotchas
+- **The prop is `setting`, NOT `settingName`** -- the source code uses `setting` as the prop name for the setting key
+- `schema` is also a setting name (not an inline object) -- it references a separate Fluent setting that contains the JSON schema definition
+- The component validates that `context` is one of `ACCOUNT`, `RETAILER`, or `AGENT` -- invalid values cause the form to not render
+- `contextId` is required to be a valid integer -- if the template string evaluates to NaN, the form will not render and submit will be blocked
+- When the setting does not yet exist at the specified context level, the form shows an "Override Default" button (create mode). When it exists, it shows "Submit" (update mode)
+- Schema and setting value types must match (JSON/INTEGER/BOOLEAN/STRING) -- a mismatch logs an error and the form does not render
+- The form uses the `useSchema` hook to dynamically generate form fields from the schema setting's value
+
+## Validation Rules
+P18 (needs setting name or reference)
+
+## Manifest Example
+```json
+{
+  "component": "fc.settingForm",
+  "props": {
+    "setting": "orderWorkflowConfig",
+    "schema": "orderWorkflowConfig_schema",
+    "context": "RETAILER",
+    "contextId": "{{activeRetailer.id}}",
+    "title": "Order Workflow Configuration"
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.sourcing.profile.drawer.button.md

@@ -0,0 +1,19 @@
+---
+alias: "fc.sourcing.profile.drawer.button"
+aliases:
+  - fc.sourcing.profile.drawer.button
+category: action
+module: Core
+---
+# fc.sourcing.profile.drawer.button
+
+Drawer button for viewing and editing sourcing profiles.
+
+## When to Use
+- Sourcing profile detail/edit UI
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.sourcing.profile.modal.button.md

@@ -0,0 +1,64 @@
+---
+alias: "fc.sourcing.profile.modal.button"
+aliases:
+  - fc.sourcing.profile.modal.button
+category: action
+module: Core
+---
+
+# fc.sourcing.profile.modal.button
+
+Modal confirmation button for sourcing profile activation. Opens a confirmation modal and executes the `activateSourcingProfile` GraphQL mutation.
+
+## When to Use
+- Add an "Activate" action button on a sourcing profile detail page
+- Trigger sourcing profile activation with a confirmation dialog
+- Provide a safe activation workflow with cancel/confirm options
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `action` | `"activate"` | Yes | Action type (currently only `"activate"` is supported) |
+| `label` | string | Yes | Button label text (translatable) |
+| `title` | string | Yes | Modal title text (translatable) |
+| `description` | string | No | Description text shown in the modal body (translatable) |
+| `style` | `"Primary"` / `"Secondary"` | No | Button visual style. Defaults to the context style from `useStyle()` or `"Primary"`. |
+
+## Data Binding
+Reads route parameters from `useData().variables.routeParams` to construct the mutation input for `activateSourcingProfile`. After successful activation, navigates to the activated profile's detail page using the returned `ref` and `version`.
+
+## Descendants
+No -- renders a single button that opens a modal on click.
+
+## Composition Patterns
+- `fc.page.section.header` > `fc.sourcing.profile.modal.button` as a header action
+- `fc.button.bar` > `fc.sourcing.profile.modal.button` alongside other sourcing profile actions
+- Typically used on sourcing profile detail pages as a page-level or section-level action
+
+## Gotchas
+- Only supports `action: "activate"` -- the component hardcodes the `activateSourcingProfile` mutation.
+- On success, clears all modals and drawers, then navigates to `sourcingProfiles/{ref}/{version}` via hash routing.
+- On error, shows an error snackbar with translated message `fc.sourcingProfileModalButton.error.confirmError`.
+- The modal uses translated labels: `fc.sourcingProfileModalButton.cancel.label` (Cancel) and `fc.sourcingProfileModalButton.confirm.label` (Confirm).
+- Button style defaults to the page context style (from `useStyle()` which reads the page actions context), falling back to `"Primary"`.
+- Registered with category `content` in the component registry.
+
+## Manifest Example
+```json
+{
+  "component": "fc.sourcing.profile.modal.button",
+  "props": {
+    "action": "activate",
+    "label": "fc.sourcingProfile.activate.label",
+    "title": "fc.sourcingProfile.activate.title",
+    "description": "fc.sourcingProfile.activate.description",
+    "style": "Primary"
+  }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.sourcing.strategy.modal.button.md

@@ -0,0 +1,20 @@
+---
+alias: "fc.sourcing.strategy.modal.button"
+aliases:
+  - fc.sourcing.strategy.modal.button
+category: action
+module: Core
+---
+# fc.sourcing.strategy.modal.button
+
+Modal button for configuring sourcing strategies — conditions, criteria, and scoring.
+
+## When to Use
+- Sourcing profile management pages
+- Strategy configuration UI
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.stepper.md

@@ -0,0 +1,20 @@
+---
+alias: "fc.stepper"
+aliases:
+  - fc.stepper
+category: content
+module: Core
+---
+# fc.stepper
+
+Linear step progress bar showing completed/current/pending steps.
+
+## When to Use
+- Order lifecycle status display
+- Multi-step process visualization
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.tab.content.md

@@ -0,0 +1,56 @@
+---
+alias: "fc.tab.content"
+aliases:
+  - fc.tab.content
+  - shared.components.material.SubLayoutContent
+category: layout
+module: Core
+---
+
+# fc.tab.content
+
+Transparent content wrapper for a single tab panel inside `fc.tabs`.
+
+## When to Use
+- Wrap the content of each tab panel inside `fc.tabs`
+- Group multiple components under a single tab
+
+## Key Props
+
+This component has no props. It is a pure pass-through that renders `<Children />`.
+
+## Descendants
+Yes -- accepts any components as children. All descendants are rendered directly.
+
+## Composition Patterns
+- `fc.tabs` > `fc.tab.content` (one per tab, each containing the tab's components)
+- `fc.tab.content` > `fc.column` + `fc.column` for multi-column tab content
+- `fc.tab.content` > `fc.list` for a list-based tab
+
+## Gotchas
+- This component renders no DOM of its own -- it is a pure `<Children />` pass-through.
+- Must be used as a direct descendant of `fc.tabs` for correct tab index mapping.
+- Registered with category `layout`.
+
+## Manifest Example
+```json
+{
+  "component": "fc.tab.content",
+  "descendants": [
+    {
+      "component": "fc.card.attribute",
+      "props": { "title": "Order Details" }
+    },
+    {
+      "component": "fc.list",
+      "props": { "title": "Line Items" }
+    }
+  ]
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.tabs.card.md

@@ -0,0 +1,64 @@
+---
+alias: "fc.tabs.card"
+aliases:
+  - fc.tabs.card
+category: layout
+module: Core
+---
+# fc.tabs.card
+
+Material-UI Card with internal tab navigation. Each tab displays different descendant content by index.
+
+## When to Use
+- Organize entity detail page into sections (Items, Fulfilments, Activity)
+- Group related content with tab navigation
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `tabs` | TabInfo[] | **Yes** | Tab definitions: `[{ label: "Items" }, { label: "Fulfilments" }]`. Alias: `layouts` also accepted |
+| `width` | CardWidth | No | Card width (quarter/third/half/full or 1-12) |
+| `urlKey` | string | No | URL parameter key for tab state persistence |
+| `noCard` | boolean | No | Remove the card wrapper (transparent background, no elevation) |
+
+## Data Binding
+None — descendants inherit parent data context.
+
+## Descendants
+Yes — each descendant corresponds to a tab by index (descendant[0] = tab[0]).
+
+## Composition Patterns
+- Tab "Items" -> `fc.list` (dataSource: entity.items)
+- Tab "Fulfilments" -> `fc.list` (dataSource: entity.fulfilments)
+- Tab "Activity" -> `fc.activity.entity`
+- Tab "Attributes" -> `fc.card.attributes.grid`
+
+## Gotchas
+- Number of tabs MUST match number of descendants -- mismatch causes empty tabs
+- Each tab `label` is required
+- Tab content is lazy-rendered (only active tab mounts)
+- **Internal prop name is `layouts`** -- the component internally uses `layouts: TabInfo[]`, but `tabs` is also accepted in the manifest. Internally resolved as `tabs || layouts || []`. Either name works in the manifest, but `tabs` is the conventional choice
+
+## Validation Rules
+P10 (CRITICAL — tabs required), P11 (tab count should match descendants)
+
+## Manifest Example
+```json
+{
+  "component": "fc.tabs.card",
+  "props": {
+    "tabs": [{ "label": "Items" }, { "label": "Fulfilments" }, { "label": "Activity" }]
+  },
+  "descendants": [
+    { "component": "fc.list", "props": { "dataSource": "orderById.items.edges", "attributes": [] } },
+    { "component": "fc.list", "props": { "dataSource": "orderById.fulfilments.edges", "attributes": [] } },
+    { "component": "fc.activity.entity" }
+  ]
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.tabs.md

@@ -0,0 +1,69 @@
+---
+alias: "fc.tabs"
+aliases:
+  - fc.tabs
+  - shared.components.material.MaterialTabsSet
+category: layout
+module: Core
+---
+
+# fc.tabs
+
+Page-level tab bar that creates URL-driven tab navigation with scrollable Material-UI tabs.
+
+## When to Use
+- Create top-level tab navigation on a page where each tab has its own URL segment
+- Switch between different content views using browser-navigable tabs
+- Build tabbed layouts where tab state persists in the URL
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `layouts` | TabInfo[] | Yes | Array of tab definitions: `{ label: string, urlValue?: string }` |
+| `urlKey` | string | No | URL query parameter key used to track the active tab in the browser URL |
+
+### TabInfo Structure
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `label` | string | Yes | Display text for the tab |
+| `urlValue` | string | No | Value written to the URL when this tab is active |
+
+## Descendants
+Yes -- each descendant corresponds to a tab panel. The active tab index determines which descendant is rendered via `<Children index={value} />`.
+
+## Composition Patterns
+- `fc.page` > `fc.tabs` > `fc.tab.content` (one per tab)
+- `fc.tabs` > any component (rendered as indexed tab panels)
+
+## Gotchas
+- This is DIFFERENT from `fc.tabs.card` -- `fc.tabs` creates URL segments for navigation, while `fc.tabs.card` is a visual-only card-level tab set.
+- The `layouts` prop defines the tab labels and URL values; descendants define the tab content. The count of `layouts` must match the count of descendants.
+- Tab state is managed via `useTabs` hook which syncs with the URL. Changing tabs updates the browser URL.
+- The tab bar is scrollable (`variant="scrollable"`) to handle many tabs without overflow.
+- Registered with category `layout`.
+
+## Manifest Example
+```json
+{
+  "component": "fc.tabs",
+  "props": {
+    "layouts": [
+      { "label": "Details", "urlValue": "details" },
+      { "label": "Items", "urlValue": "items" },
+      { "label": "History", "urlValue": "history" }
+    ],
+    "urlKey": "tab"
+  },
+  "descendants": [
+    { "component": "fc.tab.content", "descendants": [...] },
+    { "component": "fc.tab.content", "descendants": [...] },
+    { "component": "fc.tab.content", "descendants": [...] }
+  ]
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.

package/content/dev/skills/fluent-mystique-builder/components/fc.tile.metric.md

@@ -0,0 +1,73 @@
+---
+alias: "fc.tile.metric"
+aliases:
+  - fc.tile.metric
+category: content
+module: Core
+---
+# fc.tile.metric
+
+> **NOTE: `fc.tile.metric` is NOT a registered component in the Mystique core source.** It is not found in `ComponentRegistry.register()`. The closest match is `fc.dashboard.threshold` (registered as `ThresholdTile`), which provides identical functionality. Use `fc.dashboard.threshold` instead and simply omit `thresholdLow`/`thresholdHigh` for a simple metric tile without threshold coloring.
+
+Simple KPI tile displaying a label and value. Equivalent to `fc.dashboard.threshold` with no threshold props set -- the tile renders green (#4CAF50) by default when thresholds are omitted.
+
+## When to Use
+- Use `fc.dashboard.threshold` instead -- this alias is not registered in core Mystique
+- Simple count tiles (Orders Today, Pending Fulfilments) work by using `fc.dashboard.threshold` without threshold props
+
+## Key Props
+Same as `fc.dashboard.threshold` -- see that component for the full prop reference.
+
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `label` | string | No | Metric label text (supports templates) |
+| `value` | string/number | No | Metric value (supports templates) |
+| `link` | string | No | Click navigation URL (supports templates) |
+| `width` | CardWidth | No | Tile width (default: `quarter` / 3) |
+| `variant` | `'large'` or `'small'` | No | Value font size: `large` = 54px center, `small` = 36px left (default: `large`) |
+| `options` | TileOptions | No | Conditional styling based on value (see below) |
+
+### Expression-Based Conditional Styling
+
+Use `options.styles[]` to change tile text/icon color based on data values:
+
+```json
+{
+  "options": {
+    "styles": [
+      {
+        "expression": "{{gt orders.edges.length 10}}",
+        "text": { "color": "error" }
+      }
+    ]
+  }
+}
+```
+
+When `expression` evaluates to truthy, the style is applied. This works on both `fc.tile.metric` and `fc.dashboard.threshold`.
+
+## Data Binding
+Value supports template strings.
+
+## Descendants
+No.
+
+## Gotchas
+- **Not a distinct component registration** -- `fc.tile.metric` does not appear in the Mystique core component registry. If a deployment uses this name, it may be registered via a custom plugin or extension. The standard approach is to use `fc.dashboard.threshold` without threshold props
+
+## Validation Rules
+P12 (CRITICAL -- both label and value required)
+
+## Manifest Example
+```json
+{
+  "component": "fc.dashboard.threshold",
+  "props": { "label": "Orders Today", "value": "{{todayCount}}", "link": "/orders?created=today" }
+}
+```
+
+## AI Parse Notes
+- **Primary intent:** Declarative Mystique component definition for manifests.
+- **Selection signals:** Match by `alias`, category, and required `Key Props`.
+- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
+- **Safety checks:** Validate required props and data bindings before manifest generation.