@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-mystique-builder/components/fc.button.print.download.md

@@ -0,0 +1,53 @@
+---
+alias: "fc.button.print.download"
+aliases:
+  - fc.button.print.download
+category: action
+module: Core
+---
+# fc.button.print.download
+
+File download button that fetches authenticated HTML documents from Fluent APIs and presents them for download, print preview, or new-tab viewing. Used for pack slips and other API-generated HTML documents that require authentication.
+
+## When to Use
+- Downloading pack slips or invoices generated by Fluent APIs
+- Any page action that needs to fetch and present an authenticated HTML endpoint
+- Warehouse/fulfilment pages needing direct document download
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `label` | string | **Yes** | Button label text (supports i18n keys) |
+| `href` | string | **Yes** | Relative path of the Fluent API endpoint to download |
+| `filename` | string | **Yes** | Download filename. Supports template strings (e.g., appending wave ID to avoid clashes). |
+| `behavior` | string | No | How the document is presented. Default: `"preview"`. Options: `"print"` (browser print preview), `"preview"` (download as PDF), `"newTab"` (open PDF in new tab). |
+
+## Data Binding
+The `href` prop points to a relative Fluent API endpoint. The component handles authentication automatically. The `filename` prop supports template strings to generate dynamic filenames based on page data context.
+
+## Descendants
+No.
+
+## Gotchas
+- Unlike `fc.button.print.inline`, this variant downloads from a Fluent API endpoint rather than rendering from an HTML setting template.
+- The `href` must be a relative path -- the component prepends the Fluent API base URL.
+- Use template strings in `filename` to prevent file name collisions (e.g., `"packslip-{{waveId}}.pdf"`).
+
+## Manifest Example
+```json
+{
+  "component": "fc.button.print.download",
+  "props": {
+    "label": "i18n:fc.wave.downloadPackSlip",
+    "href": "/api/v4.1/wave/{{id}}/packslip",
+    "filename": "packslip-{{ref}}.pdf",
+    "behavior": "preview"
+  }
+}
+```
+
+## 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.button.print.inline.compatibility.md

@@ -0,0 +1,60 @@
+---
+alias: "fc.button.print.inline.compatibility"
+aliases:
+  - fc.button.print.inline.compatibility
+  - fc.button.print.inline
+category: action
+module: OMS
+---
+# fc.button.print.inline.compatibility
+
+Legacy compatibility variant of inline print action behavior for manifests that use older print wiring.
+
+## One-line Description
+Renders an inline print action with backward-compatible behavior for existing print templates.
+
+## When to Use
+- Existing manifests that rely on compatibility-mode inline print behavior
+- Transitional migrations from old inline print implementations
+- Operational screens requiring inline print action continuity
+
+## Key Props
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| label | string | Yes | Button text displayed in the UI |
+| setting | string | Yes | Setting key that resolves print template/config |
+
+## Data Binding
+Resolves print configuration from the supplied `setting` key and executes print action inline.
+
+## Descendants
+No.
+
+## Composition Patterns
+- Use alongside card/list rows where print is a contextual action.
+- Prefer canonical `fc.button.print.inline` unless compatibility behavior is explicitly required.
+
+## Gotchas
+- Requires valid print template configuration in the referenced setting.
+- Keep template payload shape backward compatible for legacy clients.
+
+## Validation Rules
+- `label` and `setting` should both be non-empty strings.
+- Referenced setting should exist in the target retailer/account context.
+
+## Manifest Example
+```json
+{
+  "component": "fc.button.print.inline.compatibility",
+  "props": {
+    "label": "Print Label",
+    "setting": "print.inline.template"
+  }
+}
+```
+
+## 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.button.print.inline.md

@@ -0,0 +1,53 @@
+---
+alias: "fc.button.print.inline"
+aliases:
+  - fc.button.print.inline
+  - fc.button.print.inline.compatibility
+category: action
+module: Core
+---
+# fc.button.print.inline
+
+Embedded inline print button that combines page query data with an HTML setting template to generate printable documents. Opens a modal preview with a print action. Legacy variant -- the newer `fc.button.print` is preferred for new implementations.
+
+## When to Use
+- Printing pick lists, packing slips, or order invoices from a detail page
+- Pages requiring HTML template-based document generation
+- Legacy implementations using pre-existing custom pick list templates
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `label` | string | **Yes** | Button label text (supports i18n keys) |
+| `setting` | string | **Yes** | Name of a Fluent setting containing an HTML document template. The template supports template strings referencing page query data. |
+
+## Data Binding
+The `setting` prop references a Fluent Commerce setting that contains an HTML template. The component merges page query data into the template using template strings, then renders the result in a modal preview for printing.
+
+The `fc.button.print.inline.compatibility` alias is designed for use with pre-existing custom pick list templates (saved under setting name `PICK_N_PACK_CUSTOM_PICK_LIST`). That version performs data transformation before rendering because the legacy template format requires a specific data structure not easily generated from GraphQL.
+
+## Descendants
+No.
+
+## Gotchas
+- This is a **legacy** design. For new implementations, use `fc.button.print` instead.
+- The "compatibility" alias (`fc.button.print.inline.compatibility`) handles data transformation for legacy `PICK_N_PACK_CUSTOM_PICK_LIST` templates.
+- On click, a modal preview appears with a print button that triggers the browser's native print action.
+- The HTML template in the setting can contain mustache-style template strings referencing data from the page query.
+
+## Manifest Example
+```json
+{
+  "component": "fc.button.print.inline",
+  "props": {
+    "label": "i18n:fc.fulfilment.printPickList",
+    "setting": "PICK_N_PACK_CUSTOM_PICK_LIST"
+  }
+}
+```
+
+## 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.button.print.md

@@ -0,0 +1,24 @@
+---
+alias: "fc.button.print"
+aliases:
+  - fc.button.print
+  - fc.button.print.download
+  - fc.button.print.inline
+  - fc.button.print.pick
+category: action
+module: Core
+---
+# fc.button.print
+
+Print/download button with variants: `fc.button.print.download` (file download), `fc.button.print.inline` (embedded print), `fc.button.print.pick` (pick list print).
+
+## When to Use
+- Print order documents
+- Download packing slips
+- Print pick lists for warehouse
+
+## 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.button.print.pick.md

@@ -0,0 +1,61 @@
+---
+alias: "fc.button.print.pick"
+aliases:
+  - fc.button.print.pick
+category: action
+module: Store
+---
+
+# fc.button.print.pick
+
+Store module print button that generates a pick list document by fetching and transforming wave item data, then delegates to the core `fc.button.print` component.
+
+## When to Use
+- Print a pick list for a wave in the Store (pick/pack) module
+- Generate formatted pick documents with product details, quantities, and on-hand inventory
+- Provide a print/download button on wave detail pages
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `label` | string | Yes | Button text label |
+| `setting` | string | Yes | Setting key for the print template configuration |
+| `data` | any | No | Data context containing `waveById.id` -- the wave ID to fetch items for |
+| `behavior` | `"newTab"` / `"print"` / `"download"` | No | How the document is presented. Default: `"print"` |
+
+## Data Binding
+Fetches wave items via a built-in GraphQL query (`waveById`) using the wave ID from the data context. For each item, also fetches virtual position (on-hand quantity) from the location context. Transforms the raw wave data into a structured format with:
+- `requiredQty` -- quantity needed for the pick
+- `sku.name`, `sku.skuRef`, `sku.productRef`, `sku.catalogueRef` -- product details
+- `sku.onHand` -- current on-hand quantity from virtual positions
+- `sku.references.BARCODE` -- GTIN/barcode for scanning
+- `sku.category`, `sku.imageUrlRef` -- product metadata
+
+## Composition Patterns
+- `fc.page.section.header` > `fc.button.print.pick` for a print button in a wave detail header
+- `fc.button.bar` > `fc.button.print.pick` alongside other action buttons
+
+## Gotchas
+- This is the V2 version (`InlineCompatibilityV2`) registered by the Store plugin. It delegates to `fc.button.print` (the core print component), not the older `fc.button.print.inline`.
+- The wave data transformation happens asynchronously -- items are fetched and virtual positions are queried per-item, so the transformed data populates incrementally.
+- Requires the Store module to be loaded -- this component is registered in `mystique-store`, not core.
+- The `data` prop must contain `waveById.id` for the wave query to work. Typically this comes from the page-level data context on a wave detail page.
+- The older `fc.button.print.inline.compatibility` (V1) delegates to `fc.button.print.inline` instead.
+
+## Manifest Example
+```json
+{
+  "component": "fc.button.print.pick",
+  "props": {
+    "label": "Print Pick List",
+    "setting": "fc.mystique.picklist.template",
+    "behavior": "print"
+  }
+}
+```
+
+## 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.buttons.add.reject.md

@@ -0,0 +1,20 @@
+---
+alias: "fc.buttons.add.reject"
+aliases:
+  - fc.buttons.add.reject
+category: action
+module: Store
+---
+# fc.buttons.add.reject
+
+Action button pair for pack/reject operations in store fulfilment workflows.
+
+## When to Use
+- Store fulfilment pack screen
+- Accept/reject item actions
+
+## 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.card.attribute.md

@@ -0,0 +1,73 @@
+---
+alias: "fc.card.attribute"
+aliases:
+  - fc.card.attribute
+  - shared.components.material.DynamicCard
+category: content
+module: Core
+---
+# fc.card.attribute
+
+Key-value display card showing entity data as labeled attribute pairs.
+
+## When to Use
+- Entity summary sidebar (order ref, status, type, customer)
+- Detail cards showing specific field groups
+- Any structured key-value display
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `attributes` | Attribute[] | **Yes** | Key-value pairs: `[{ label: "Status", value: "{{status}}" }]` |
+| `title` | string | No | Card header title |
+| `highlight` | string | No | Card top-border highlight color (theme color key or CSS color) |
+| `width` | CardWidth | No | Card width (quarter/third/half/full or 1-12) |
+| `cardImage` | CardImageProps | No | Image display in card: `{ imageUrl: "{{imageUrl}}", width?: number\|string, height?: number\|string }`. Default size 80x80. URL supports template strings |
+| `hideLabels` | boolean | No | Hide attribute labels, show only values (full-width) |
+| `link` | string | No | Template string for click navigation: `"/orders/{{id}}"`. Makes the entire card clickable |
+| `topAction` | boolean | No | Place card action buttons at the top next to title instead of at the bottom (inherited from Card) |
+| `fitContent` | boolean | No | Set card height to `fit-content` instead of `auto` (inherited from Card) |
+| `onClick` | function | No | Click handler (inherited from Card). Makes card clickable with hover elevation effect |
+
+## Data Binding
+Optional `dataSource` scopes data context. Attribute `value` uses template strings: `"{{order.ref}}"`, `"{{dateFormat createdOn 'MMM DD'}}"`.
+
+## Descendants
+No.
+
+## Composition Patterns
+- `fc.column(third)` > `fc.card.attribute` for sidebar summary
+- Multiple `fc.card.attribute` in a column for grouped fields
+- Inside `fc.conditional` for type-specific cards
+
+## Gotchas
+- `attributes` array is required -- empty card renders nothing useful
+- Template values evaluate against the data context (page data or dataSource scoped)
+- `cardImage` renders a default placeholder SVG when `imageUrl` evaluates to empty/null
+- `link` prop on AttributesCard makes the whole card clickable (navigates on click, ignores if user has selected text)
+- Individual attributes support `enableCopyIcon` (`"displayAlways"` or `"displayOnHover"`) for copy-to-clipboard
+
+## Validation Rules
+P05 (CRITICAL — attributes required), P17 (width valid)
+
+## Manifest Example
+```json
+{
+  "component": "fc.card.attribute",
+  "props": {
+    "title": "Order Summary",
+    "attributes": [
+      { "label": "Ref", "value": "{{ref}}" },
+      { "label": "Status", "value": "{{status}}" },
+      { "label": "Type", "value": "{{type}}" },
+      { "label": "Created", "value": "{{dateFormat createdOn 'MMM DD, YYYY'}}" }
+    ]
+  }
+}
+```
+
+## 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.card.attributes.grid.md

@@ -0,0 +1,40 @@
+---
+alias: "fc.card.attributes.grid"
+aliases:
+  - fc.card.attributes.grid
+category: content
+module: Core
+---
+# fc.card.attributes.grid
+
+Auto-display all entity attributes in a 4-column grid layout without explicit field definitions.
+
+## When to Use
+- "Show all attributes" tab in entity detail page
+- Quick attribute overview without specifying each field
+- Debugging / inspection views
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `exclude` | string[] | No | Attribute names to hide: `["internalId", "password"]` |
+
+## Data Binding
+**Requires `dataSource`** pointing to an attributes array or entity.
+
+## Descendants
+No.
+
+## Manifest Example
+```json
+{
+  "component": "fc.card.attributes.grid",
+  "props": { "dataSource": "orderById.attributes", "exclude": ["internalId"] }
+}
+```
+
+## 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.card.image.md

@@ -0,0 +1,37 @@
+---
+alias: "fc.card.image"
+aliases:
+  - fc.card.image
+category: content
+module: Core
+---
+# fc.card.image
+
+Image display within a card container with responsive sizing.
+
+## When to Use
+- Product images
+- Document/receipt thumbnails
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `image` | { imageUrl, width?, height? } | **Yes** | Image source and dimensions |
+| `width` | CardWidth | No | Card width |
+
+## Validation Rules
+P14 (CRITICAL — image with imageUrl required)
+
+## Manifest Example
+```json
+{
+  "component": "fc.card.image",
+  "props": { "image": { "imageUrl": "{{imageUrl}}", "width": 200 } }
+}
+```
+
+## 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.card.map.point.md

@@ -0,0 +1,24 @@
+---
+alias: "fc.card.map.point"
+aliases:
+  - fc.card.map.point
+category: content
+module: OMS
+---
+# fc.card.map.point
+
+Google Maps display with a location pin marker.
+
+## When to Use
+- Store/warehouse detail pages
+- Delivery address visualization
+- Location overview pages
+
+## Data Binding
+Expects latitude/longitude in data context.
+
+## 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.card.multi.md

@@ -0,0 +1,79 @@
+---
+alias: "fc.card.multi"
+aliases:
+  - fc.card.multi
+category: content
+module: Core
+---
+
+# fc.card.multi
+
+Card container that nests multiple child components within a single Material-UI card, with configurable title, width, and layout direction.
+
+## When to Use
+- Grouping several related components (charts, attributes, actions) into one visual card
+- Creating composite detail cards with mixed content types
+- Any situation where multiple components should share a single card border and title
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| `title` | string | No | Card header title text |
+| `width` | CardWidth (`"quarter"` / `"third"` / `"half"` / `"two-thirds"` / `"full"` / number 1-12) | No | Card width on 12-column grid (default: `"full"`) |
+| `direction` | `"row"` / `"column"` | No | Layout direction for children (default: `"row"`) |
+
+## Data Binding
+Standard `dataSource` configuration applies. Child components inherit the data context.
+
+## Descendants
+Yes -- accepts any component or array of components. Children are laid out in the specified `direction`.
+
+## Composition Patterns
+- `fc.column` > `fc.card.multi` > multiple `fc.card.attribute` or chart components
+- `fc.card.multi(direction: "column")` > stacked content blocks
+- `fc.card.multi(direction: "row")` > side-by-side widgets within one card
+- `fc.tabs.card` > `fc.card.multi` per tab for grouped tab content
+
+## Gotchas
+- Default direction is `"row"` -- children display side by side unless you set `direction: "column"`.
+- On mobile devices, width auto-collapses to 12 (full width) regardless of setting.
+- Named widths map to grid values: quarter=3, third=4, half=6, two-thirds=8, full=12.
+- Unlike `fc.page.section`, this component renders a visible card with border and optional title.
+- Not found in the current core source snapshots -- may be registered by a newer version or runtime plugin. Documented in OMX component docs.
+
+## Manifest Example
+```json
+{
+  "component": "fc.card.multi",
+  "props": {
+    "title": "Order Overview",
+    "width": "two-thirds",
+    "direction": "column"
+  },
+  "descendants": [
+    {
+      "component": "fc.card.attribute",
+      "props": {
+        "attributes": [
+          { "label": "Ref", "value": "{{ref}}" },
+          { "label": "Status", "value": "{{status}}" }
+        ]
+      }
+    },
+    {
+      "component": "fc.chart.bar",
+      "props": {
+        "dataSource": "metrics",
+        "bars": [{ "dataKey": "count", "fill": "#1976d2" }],
+        "xAxis": { "dataKey": "label" }
+      }
+    }
+  ]
+}
+```
+
+## 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.card.product.md

@@ -0,0 +1,27 @@
+---
+alias: "fc.card.product"
+aliases:
+  - fc.card.product
+category: content
+module: Core
+---
+# fc.card.product
+
+Product display card with image, name, SKU, and inventory information.
+
+## When to Use
+- Product detail pages
+- Order item product previews
+- Product catalog browsing
+
+## Data Binding
+Expects product data in context (name, imageUrl, sku, etc.).
+
+## Descendants
+No.
+
+## 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.chart.area.md

@@ -0,0 +1,34 @@
+---
+alias: fc.chart.area
+aliases:
+  - fc.chart.area
+  - fc.chart.area.wrapper.feed
+category: content
+module: Core
+---
+
+# fc.chart.area
+
+Recharts-based area chart for cumulative data visualization.
+
+## When to Use
+- Cumulative metrics, filled trend lines
+
+## Key Props
+| Prop | Type | Required | What it controls |
+|------|------|----------|------------------|
+| dataSource | string | Yes | Path to chart data |
+| areas | ChartSeries[] | No | Series with dataKey and color |
+| xAxis | AxisConfig | No | X-axis configuration |
+| yAxis | AxisConfig | No | Y-axis configuration |
+| legend | boolean | No | Show/hide legend |
+| tooltip | boolean | No | Show/hide tooltip |
+| title | string | No | Chart title |
+| width | CardWidth | No | Card width |
+ 
+
+## 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.