@lostgradient/cinder 0.1.1 → 0.2.0

package/src/components/menu-bar/README.md

@@ -0,0 +1,53 @@
+# MenuBar
+
+Command menubar for application chrome such as File, Edit, and View menus.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { MenuBar } from '@lostgradient/cinder/menu-bar';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Building a desktop-style command menubar with dropdown command groups.
+- Exposing top-level application menus that need arrow-key traversal and optional submenus.
+
+### Avoid When
+
+- Linking between routes or sections — use navigation-bar or side-navigation instead.
+- Showing one standalone trigger with a menu — use dropdown, dropdown-menu, and dropdown-item directly.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop         | Type       | Required | Default | Description                                                                                             |
+| ------------ | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `class`      | `string`   | no       | —       |                                                                                                         |
+| `id`         | `string`   | no       | —       |                                                                                                         |
+| `label`      | `string`   | no       | —       |                                                                                                         |
+| `labelledBy` | `string`   | no       | —       |                                                                                                         |
+| `menus`      | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/navigation-bar/README.md

@@ -18,11 +18,11 @@ Top-level horizontal navigation bar for primary site or app destinations.
 
 | Prop             | Type       | Required | Default | Description                                                                                                                |
 | ---------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`          | `string`   | no       | —       | Custom class merged onto the root `<nav>` element.                                                                         |
 | `mobileMenuOpen` | `boolean`  | no       | —       | Two-way bindable open state of the mobile menu.                                                                            |
 | `navAriaLabel`   | `string`   | no       | —       | Accessible name for the <nav> landmark. Wins over any aria-label passed via rest. Default 'Main navigation'.               |
 | `actions`        | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `brand`          | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
-| `class`          | `(opaque)` | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact signature.                    |
 | `items`          | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 | `menuToggle`     | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
 

package/src/components/navigation-bar/navigation-bar.schema.json

@@ -2,6 +2,10 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
+    "class": {
+      "type": "string",
+      "description": "Custom class merged onto the root `<nav>` element."
+    },
     "mobileMenuOpen": {
       "type": "boolean",
       "description": "Two-way bindable open state of the mobile menu."
@@ -22,10 +26,6 @@
         "name": "brand",
         "reason": "function-or-snippet"
       },
-      {
-        "name": "class",
-        "reason": "unknown-shape"
-      },
       {
         "name": "items",
         "reason": "function-or-snippet"

package/src/components/navigation-bar/navigation-bar.schema.ts

@@ -4,6 +4,10 @@ const schema = {
   $schema: 'https://json-schema.org/draft/2020-12/schema',
   type: 'object',
   properties: {
+    class: {
+      type: 'string',
+      description: 'Custom class merged onto the root `<nav>` element.',
+    },
     mobileMenuOpen: {
       type: 'boolean',
       description: 'Two-way bindable open state of the mobile menu.',
@@ -25,10 +29,6 @@ const schema = {
         name: 'brand',
         reason: 'function-or-snippet',
       },
-      {
-        name: 'class',
-        reason: 'unknown-shape',
-      },
       {
         name: 'items',
         reason: 'function-or-snippet',

package/src/components/navigation-bar/navigation-bar.types.ts

@@ -11,7 +11,8 @@ export type NavigationBarToggleAttributes = {
 export type NavigationBarItemsContext = {
   variant: NavigationVariant;
 };
-export type NavigationBarProps = HTMLAttributes<HTMLElement> & {
+export type NavigationBarProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Custom class merged onto the root `<nav>` element. */
   class?: string;
   brand?: Snippet;
   /** Receives a context object with the current variant. */

package/src/components/pricing-card/README.md

@@ -0,0 +1,55 @@
+# PricingCard
+
+Presents a single pricing plan with its name, price, feature list, an optional caveat line, and a call-to-action button, with a selectable/active state.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { PricingCard } from '@lostgradient/cinder/pricing-card';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Letting users compare and select subscription tiers or product plans.
+- Highlighting one tier as selected or recommended in a pricing comparison.
+
+### Avoid When
+
+- Showing generic grouped content without a distinct price or CTA — use card instead.
+- Displaying a single key metric in isolation — use stat or stat-group instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop       | Type       | Required | Default | Description                                            |
+| ---------- | ---------- | -------- | ------- | ------------------------------------------------------ |
+| `caveat`   | `string`   | no       | —       | Optional footnote or caveat beneath the features list. |
+| `class`    | `string`   | no       | —       | Custom class merged with `.cinder-pricing-card`.       |
+| `cta`      | `string`   | yes      | —       | Label for the call-to-action button.                   |
+| `features` | `string`[] | yes      | —       | Feature strings to display in the bulleted list.       |
+| `name`     | `string`   | yes      | —       | Plan name displayed as the card heading.               |
+| `price`    | `string`   | yes      | —       | Price string, e.g. "$9/mo" or "Free".                  |
+| `selected` | `boolean`  | no       | `false` | Whether this card is the currently selected plan.      |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/pricing-card/index.ts

@@ -0,0 +1,6 @@
+import './pricing-card.css';
+import PricingCard from './pricing-card.svelte';
+
+export default PricingCard;
+export type { PricingCardProps } from './pricing-card.types.ts';
+export { PricingCard };

package/src/components/pricing-card/pricing-card.css

@@ -0,0 +1,173 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  /* ========================================
+ * PRICING CARD
+ * ======================================== */
+
+  .cinder-pricing-card {
+    container-type: inline-size;
+    container-name: cinder-pricing-card;
+    display: flex;
+    flex-direction: column;
+    inline-size: 100%;
+    border-radius: var(--cinder-radius-lg);
+    background: var(--cinder-surface-raised);
+    border: 1px solid var(--cinder-border-muted);
+    color: var(--cinder-text);
+    box-shadow: var(--cinder-shadow-sm);
+    overflow: hidden;
+    transition:
+      border-color var(--cinder-duration-fast) var(--cinder-ease-standard),
+      box-shadow var(--cinder-duration-fast) var(--cinder-ease-standard);
+  }
+
+  .cinder-pricing-card[data-cinder-selected] {
+    border-color: var(--cinder-accent);
+    box-shadow:
+      var(--cinder-shadow-sm),
+      0 0 0 2px color-mix(in oklch, var(--cinder-accent), transparent 70%);
+  }
+
+  /* ----------------------------------------
+ * Header
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__header {
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-1);
+    padding: var(--cinder-space-4) var(--cinder-space-4) var(--cinder-space-3);
+    border-bottom: 1px solid var(--cinder-border-muted);
+  }
+
+  .cinder-pricing-card[data-cinder-selected] .cinder-pricing-card__header {
+    background: color-mix(in oklch, var(--cinder-accent), transparent 92%);
+  }
+
+  .cinder-pricing-card__heading-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-2);
+  }
+
+  /* Non-color cue for the selected plan (WCAG 1.4.1): a text pill in the header
+   * so selection is conveyed independently of the accent treatment. */
+  .cinder-pricing-card__selected-flag {
+    flex-shrink: 0;
+    font-size: var(--cinder-text-xs);
+    font-weight: var(--cinder-font-semibold);
+    letter-spacing: 0.025em;
+    text-transform: uppercase;
+    color: var(--cinder-accent-text);
+    background: color-mix(in oklch, var(--cinder-accent), transparent 85%);
+    border-radius: var(--cinder-radius-full);
+    padding: var(--cinder-space-1) var(--cinder-space-2);
+    line-height: 1;
+  }
+
+  /* ----------------------------------------
+ * Name & price
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__name {
+    font-size: var(--cinder-text-sm);
+    font-weight: var(--cinder-font-semibold);
+    color: var(--cinder-text);
+    margin: 0;
+    letter-spacing: 0.025em;
+    text-transform: uppercase;
+  }
+
+  .cinder-pricing-card[data-cinder-selected] .cinder-pricing-card__name {
+    color: var(--cinder-accent-text);
+  }
+
+  .cinder-pricing-card__price {
+    font-size: var(--cinder-text-3xl);
+    font-weight: var(--cinder-font-bold);
+    color: var(--cinder-text);
+    margin: 0;
+    line-height: 1;
+  }
+
+  /* ----------------------------------------
+ * Body
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__body {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-3);
+    padding: var(--cinder-space-4);
+  }
+
+  /* ----------------------------------------
+ * Features list
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__features {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--cinder-space-2);
+  }
+
+  .cinder-pricing-card__feature {
+    display: flex;
+    align-items: baseline;
+    gap: var(--cinder-space-2);
+    font-size: var(--cinder-text-sm);
+    color: var(--cinder-text);
+  }
+
+  .cinder-pricing-card__feature::before {
+    content: '';
+    display: inline-block;
+    inline-size: 0.375rem;
+    block-size: 0.375rem;
+    border-radius: var(--cinder-radius-full);
+    background: var(--cinder-accent);
+    flex-shrink: 0;
+    translate: 0 0.1em;
+  }
+
+  /* ----------------------------------------
+ * Caveat
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__caveat {
+    font-size: var(--cinder-text-xs);
+    color: var(--cinder-text-subtle);
+    margin: 0;
+    font-style: italic;
+  }
+
+  /* ----------------------------------------
+ * Footer (CTA)
+ * ---------------------------------------- */
+
+  .cinder-pricing-card__footer {
+    padding: var(--cinder-space-3) var(--cinder-space-4) var(--cinder-space-4);
+    border-top: 1px solid var(--cinder-border-muted);
+  }
+
+  /* ----------------------------------------
+ * Responsive
+ * ---------------------------------------- */
+
+  /* Shrink the price only when the card itself is genuinely cramped — near the
+   * tight end of an auto-fit grid (examples floor at ~14rem). A viewport @media
+   * here would be wrong: a pricing card reacts to its own box width, not the
+   * viewport (RESPONSIVE-POLICY.md). The previous 640px viewport breakpoint
+   * fired on phones; the equivalent container threshold is far smaller because
+   * pricing cards render at ~14–22rem, not full-viewport width. */
+  @container cinder-pricing-card (max-width: 16rem) {
+    .cinder-pricing-card__price {
+      font-size: var(--cinder-text-2xl);
+    }
+  }
+}

package/src/components/pricing-card/pricing-card.examples.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "pricing-card",
+  "import": "@lostgradient/cinder/pricing-card",
+  "examples": [
+    {
+      "id": "tiers",
+      "title": "Pricing tiers",
+      "description": "Three plan tiles side by side with one pre-selected.",
+      "code": "<script lang=\"ts\">\n  import { PricingCard } from '@lostgradient/cinder/pricing-card';\n\n  let selectedPlan = $state<'starter' | 'pro' | 'enterprise'>('pro');\n</script>\n\n<div\n  style=\"display: grid; grid-template-columns: repeat(auto-fit, minmax(14rem, 1fr)); gap: var(--cinder-space-4); align-items: start;\"\n>\n  <PricingCard\n    name=\"Starter\"\n    price=\"Free\"\n    features={['3 projects', '1 GB storage', 'Community support']}\n    cta=\"Get started\"\n    selected={selectedPlan === 'starter'}\n    onselect={() => {\n      selectedPlan = 'starter';\n    }}\n  />\n\n  <PricingCard\n    name=\"Pro\"\n    price=\"$9/mo\"\n    features={['Unlimited projects', '10 GB storage', 'Priority support', 'Custom domains']}\n    cta=\"Choose Pro\"\n    selected={selectedPlan === 'pro'}\n    onselect={() => {\n      selectedPlan = 'pro';\n    }}\n  />\n\n  <PricingCard\n    name=\"Enterprise\"\n    price=\"$49/mo\"\n    features={[\n      'Unlimited projects',\n      '500 GB storage',\n      'Dedicated support',\n      'Custom domains',\n      'SSO & audit logs',\n    ]}\n    cta=\"Contact sales\"\n    selected={selectedPlan === 'enterprise'}\n    onselect={() => {\n      selectedPlan = 'enterprise';\n    }}\n  />\n</div>\n"
+    },
+    {
+      "id": "with-caveat",
+      "title": "With caveat",
+      "description": "A pricing card with a consumer-supplied caveat beneath the feature list, useful for legal disclaimers or billing notes.",
+      "code": "<script lang=\"ts\">\n  import { PricingCard } from '@lostgradient/cinder/pricing-card';\n</script>\n\n<div style=\"max-inline-size: 22rem;\">\n  <PricingCard\n    name=\"Growth\"\n    price=\"$29/mo\"\n    features={['Unlimited projects', '50 GB storage', 'Email & chat support', 'Advanced analytics']}\n    caveat=\"Billed annually. Monthly billing available at $35/mo.\"\n    cta=\"Start free trial\"\n    onselect={() => {}}\n  />\n</div>\n"
+    }
+  ]
+}

package/src/components/pricing-card/pricing-card.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Plan name displayed as the card heading."
+    },
+    "price": {
+      "type": "string",
+      "description": "Price string, e.g. \"$9/mo\" or \"Free\"."
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Feature strings to display in the bulleted list."
+    },
+    "cta": {
+      "type": "string",
+      "description": "Label for the call-to-action button."
+    },
+    "caveat": {
+      "type": "string",
+      "description": "Optional footnote or caveat beneath the features list."
+    },
+    "selected": {
+      "type": "boolean",
+      "description": "Whether this card is the currently selected plan.",
+      "default": false
+    },
+    "class": {
+      "type": "string",
+      "description": "Custom class merged with `.cinder-pricing-card`."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["cta", "features", "name", "price"]
+}

package/src/components/pricing-card/pricing-card.schema.ts

@@ -0,0 +1,44 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Plan name displayed as the card heading.',
+    },
+    price: {
+      type: 'string',
+      description: 'Price string, e.g. "$9/mo" or "Free".',
+    },
+    features: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+      description: 'Feature strings to display in the bulleted list.',
+    },
+    cta: {
+      type: 'string',
+      description: 'Label for the call-to-action button.',
+    },
+    caveat: {
+      type: 'string',
+      description: 'Optional footnote or caveat beneath the features list.',
+    },
+    selected: {
+      type: 'boolean',
+      description: 'Whether this card is the currently selected plan.',
+      default: false,
+    },
+    class: {
+      type: 'string',
+      description: 'Custom class merged with `.cinder-pricing-card`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['cta', 'features', 'name', 'price'],
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/pricing-card/pricing-card.svelte

@@ -0,0 +1,70 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status alpha
+   * @purpose Presents a single pricing plan with its name, price, feature list, and a call-to-action button.
+   * @tag pricing
+   * @tag plan
+   * @useWhen Letting users compare and select subscription tiers or product plans.
+   * @useWhen Highlighting one tier as selected or recommended in a pricing comparison.
+   * @avoidWhen Showing generic grouped content without a distinct price or CTA — use card instead.
+   * @avoidWhen Displaying a single key metric in isolation — use stat or stat-group instead.
+   * @related card, button, stat, stat-group
+   */
+  export type { PricingCardProps } from './pricing-card.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import Button from '../button/button.svelte';
+  import type { PricingCardProps } from './pricing-card.types.ts';
+
+  let {
+    name,
+    price,
+    features,
+    cta,
+    onselect,
+    caveat,
+    selected = false,
+    class: className,
+    ...rest
+  }: PricingCardProps = $props();
+</script>
+
+<div
+  class={classNames('cinder-pricing-card', className)}
+  data-cinder-selected={selected ? '' : undefined}
+  aria-current={selected ? 'true' : undefined}
+  {...rest}
+>
+  <div class="cinder-pricing-card__header">
+    <div class="cinder-pricing-card__heading-row">
+      <h3 class="cinder-pricing-card__name">{name}</h3>
+      <!-- A visible, non-color cue for the selected plan: the accent border and
+           CTA tint alone would not be perceivable to a colour-blind sighted
+           user (WCAG 1.4.1), so the selected state also carries explicit text. -->
+      {#if selected}
+        <span class="cinder-pricing-card__selected-flag">Selected</span>
+      {/if}
+    </div>
+    <p class="cinder-pricing-card__price">{price}</p>
+  </div>
+
+  <div class="cinder-pricing-card__body">
+    <ul class="cinder-pricing-card__features">
+      {#each features as feature, index (index)}
+        <li class="cinder-pricing-card__feature">{feature}</li>
+      {/each}
+    </ul>
+
+    {#if caveat}
+      <p class="cinder-pricing-card__caveat" data-cinder-caveat="">{caveat}</p>
+    {/if}
+  </div>
+
+  <div class="cinder-pricing-card__footer">
+    <Button label={cta} variant={selected ? 'primary' : 'secondary'} fullWidth onclick={onselect} />
+  </div>
+</div>

package/src/components/pricing-card/pricing-card.types.ts

@@ -0,0 +1,49 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Props for the PricingCard component. */
+export type PricingCardProps = Omit<HTMLAttributes<HTMLDivElement>, 'onselect'> & {
+  /** Plan name displayed as the card heading. */
+  name: string;
+  /** Price string, e.g. "$9/mo" or "Free". Rendered verbatim — include any currency symbol and billing period. */
+  price: string;
+  /** List of feature strings to display. Rendered as a bulleted list. */
+  features: string[];
+  /** Label for the call-to-action button. */
+  cta: string;
+  /** Called when the CTA button is clicked. */
+  onselect: () => void;
+  /**
+   * Optional footnote or caveat displayed beneath the features list.
+   * Use for legal disclaimers, billing notes, or conditional terms.
+   * Rendered in a visually subdued style to distinguish it from the main feature list.
+   */
+  caveat?: string;
+  /**
+   * Whether this card represents the currently selected plan.
+   * Sets `data-cinder-selected` and `aria-current="true"` on the root element.
+   */
+  selected?: boolean;
+  /** Merged with the root element's class list. */
+  class?: string;
+};
+
+/** Cinder-specific props for the PricingCard component, used by the schema generator. */
+export interface PricingCardSchemaProps {
+  /** Plan name displayed as the card heading. */
+  name: string;
+  /** Price string, e.g. "$9/mo" or "Free". */
+  price: string;
+  /** Feature strings to display in the bulleted list. */
+  features: string[];
+  /** Label for the call-to-action button. */
+  cta: string;
+  /** Optional footnote or caveat beneath the features list. */
+  caveat?: string;
+  /**
+   * Whether this card is the currently selected plan.
+   * @default false
+   */
+  selected?: boolean;
+  /** Custom class merged with `.cinder-pricing-card`. */
+  class?: string;
+}

package/src/components/pricing-card/pricing-card.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/pricing-card/pricing-card.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;