@lostgradient/cinder 0.5.0 → 0.7.0

package/src/components/qr-code/qr-code.svelte

@@ -1,123 +1,79 @@
 <script lang="ts" module>
-  /**
-   * @cinder
-   * @category data-display
-   * @status beta
-   * @purpose Encodes a string payload as an inline SVG QR code with an explicit accessible label.
-   * @tag qr-code
-   * @tag sharing
-   * @useWhen Presenting a scannable URL, token, or Wi-Fi credential that users can scan from another device.
-   * @useWhen You need a theme-aware QR graphic that stays crisp at any scale.
-   * @avoidWhen You only need to expose a copyable short text value without camera scanning affordance. | copy-button
-   * @avoidWhen The payload is sensitive and should never be displayed as machine-readable visual data.
-   * @related copy-button, share-card
-   */
-  export type { QrCodeErrorCorrectionLevel, QrCodeProps } from './qr-code.types.ts';
+export {};
 </script>
 
 <script lang="ts">
-  import QRCode from 'qrcode';
-
-  import { classNames } from '../../utilities/class-names.ts';
-
-  import type { QrCodeProps } from './qr-code.types.ts';
-
-  let {
-    value,
-    label,
-    size = 160,
-    margin = 4,
-    errorCorrectionLevel = 'M',
-    class: customClassName,
-    ...rest
-  }: QrCodeProps = $props();
-
-  const mergedClassName = $derived(classNames('cinder-qr-code', customClassName));
-  const resolvedSize = $derived(Number.isFinite(size) && size > 0 ? size : 160);
-  const resolvedMargin = $derived(Number.isFinite(margin) && margin >= 0 ? Math.floor(margin) : 4);
-  const safeLabel = $derived(
-    typeof label === 'string' && label.trim().length > 0 ? label.trim() : 'QR code',
-  );
-
-  function svgCommand(command: string, x: number, y: number | undefined = undefined): string {
+import QRCode from 'qrcode';
+import { classNames } from '../../utilities/class-names.ts';
+let { value, label, size = 160, margin = 4, errorCorrectionLevel = 'M', class: customClassName, ...rest } = $props();
+const mergedClassName = $derived(classNames('cinder-qr-code', customClassName));
+const resolvedSize = $derived(Number.isFinite(size) && size > 0 ? size : 160);
+const resolvedMargin = $derived(Number.isFinite(margin) && margin >= 0 ? Math.floor(margin) : 4);
+const safeLabel = $derived(typeof label === 'string' && label.trim().length > 0 ? label.trim() : 'QR code');
+function svgCommand(command, x, y = undefined) {
     return typeof y === 'number' ? `${command}${x} ${y}` : `${command}${x}`;
-  }
-
-  function qrModulesToPath(
-    data: ArrayLike<boolean | number>,
-    moduleSize: number,
-    marginSize: number,
-  ): string {
+}
+function qrModulesToPath(data, moduleSize, marginSize) {
     let path = '';
     let moveBy = 0;
     let newRow = false;
     let lineLength = 0;
-
     for (let index = 0; index < data.length; index += 1) {
-      const column = Math.floor(index % moduleSize);
-      const row = Math.floor(index / moduleSize);
-
-      if (!column && !newRow) newRow = true;
-
-      if (data[index]) {
-        lineLength += 1;
-
-        if (!(index > 0 && column > 0 && data[index - 1])) {
-          path += newRow
-            ? svgCommand('M', column + marginSize, 0.5 + row + marginSize)
-            : svgCommand('m', moveBy, 0);
-          moveBy = 0;
-          newRow = false;
+        const column = Math.floor(index % moduleSize);
+        const row = Math.floor(index / moduleSize);
+        if (!column && !newRow)
+            newRow = true;
+        if (data[index]) {
+            lineLength += 1;
+            if (!(index > 0 && column > 0 && data[index - 1])) {
+                path += newRow
+                    ? svgCommand('M', column + marginSize, 0.5 + row + marginSize)
+                    : svgCommand('m', moveBy, 0);
+                moveBy = 0;
+                newRow = false;
+            }
+            if (!(column + 1 < moduleSize && data[index + 1])) {
+                path += svgCommand('h', lineLength);
+                lineLength = 0;
+            }
         }
-
-        if (!(column + 1 < moduleSize && data[index + 1])) {
-          path += svgCommand('h', lineLength);
-          lineLength = 0;
+        else {
+            moveBy += 1;
         }
-      } else {
-        moveBy += 1;
-      }
     }
-
     return path;
-  }
-
-  function renderSvgData(
-    modules: ArrayLike<boolean | number>,
-    moduleSize: number,
-    marginSize: number,
-  ): { pathData: string; viewBox: string } {
+}
+function renderSvgData(modules, moduleSize, marginSize) {
     const qrSize = moduleSize + marginSize * 2;
     return {
-      pathData: qrModulesToPath(modules, moduleSize, marginSize),
-      viewBox: `0 0 ${qrSize} ${qrSize}`,
+        pathData: qrModulesToPath(modules, moduleSize, marginSize),
+        viewBox: `0 0 ${qrSize} ${qrSize}`,
     };
-  }
-
-  const qrGenerationResult = $derived.by(() => {
+}
+const qrGenerationResult = $derived.by(() => {
     try {
-      const qrData = QRCode.create(value, { errorCorrectionLevel });
-      const svgData = renderSvgData(qrData.modules.data, qrData.modules.size, resolvedMargin);
-
-      return {
-        pathData: svgData.pathData,
-        viewBox: svgData.viewBox,
-        generationFailed: false,
-      };
-    } catch {
-      return {
-        pathData: '',
-        viewBox: '0 0 0 0',
-        generationFailed: true,
-      };
+        const qrData = QRCode.create(value, { errorCorrectionLevel });
+        const svgData = renderSvgData(qrData.modules.data, qrData.modules.size, resolvedMargin);
+        return {
+            pathData: svgData.pathData,
+            viewBox: svgData.viewBox,
+            generationFailed: false,
+        };
+    }
+    catch {
+        return {
+            pathData: '',
+            viewBox: '0 0 0 0',
+            generationFailed: true,
+        };
     }
-  });
-  const pathData = $derived(qrGenerationResult.pathData);
-  const viewBox = $derived(qrGenerationResult.viewBox);
-  const generationFailed = $derived(qrGenerationResult.generationFailed);
-  const resolvedRole = $derived(generationFailed ? 'status' : 'img');
-  const resolvedAriaLabel = $derived(generationFailed ? 'Unable to render QR code' : safeLabel);
-  const resolvedAriaLive = $derived(generationFailed ? 'polite' : undefined);
+});
+const pathData = $derived(qrGenerationResult.pathData);
+const viewBox = $derived(qrGenerationResult.viewBox);
+const generationFailed = $derived(qrGenerationResult.generationFailed);
+const resolvedRole = $derived(generationFailed ? 'status' : 'img');
+const resolvedAriaLabel = $derived(generationFailed ? 'Unable to render QR code' : safeLabel);
+const resolvedAriaLive = $derived(generationFailed ? 'polite' : undefined);
 </script>
 
 <span

package/src/components/qr-code/qr-code.variables.json

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

package/src/components/qr-code/qr-code.variables.ts

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

package/src/components/radio-group/radio-group.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "value": {
+      "type": "string",
+      "description": "Bound selected value."
+    },
+    "name": {
+      "type": "string",
+      "description": "Shared `name` for all radios in the group; required for native form submission."
+    },
+    "label": {
+      "type": "string",
+      "description": "Visible group caption. Rendered as a `<legend>` inside the `<fieldset>`.\nNamed `label` for consistency with every other form control — the element\nis a `<legend>` because the group is a fieldset."
+    },
+    "description": {
+      "type": "string",
+      "description": "Helper text displayed below the group; wired via `aria-describedby` on the fieldset."
+    },
+    "error": {
+      "type": "string",
+      "description": "Validation error message; sets `aria-invalid=\"true\"` on the group's children."
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disables the entire group."
+    },
+    "required": {
+      "type": "boolean",
+      "description": "When true, marks the group's radios as required for form submission."
+    },
+    "variant": {
+      "enum": ["default", "card"],
+      "description": "Visual layout. 'card' wraps each radio row in a bordered surface."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class names merged with `.cinder-radio-group`."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["name"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet",
+        "required": true,
+        "description": "Radio children."
+      }
+    ]
+  }
+}

package/src/components/radio-group/radio-group.schema.ts

@@ -0,0 +1,61 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    value: {
+      type: 'string',
+      description: 'Bound selected value.',
+    },
+    name: {
+      type: 'string',
+      description:
+        'Shared `name` for all radios in the group; required for native form submission.',
+    },
+    label: {
+      type: 'string',
+      description:
+        'Visible group caption. Rendered as a `<legend>` inside the `<fieldset>`.\nNamed `label` for consistency with every other form control — the element\nis a `<legend>` because the group is a fieldset.',
+    },
+    description: {
+      type: 'string',
+      description:
+        'Helper text displayed below the group; wired via `aria-describedby` on the fieldset.',
+    },
+    error: {
+      type: 'string',
+      description: 'Validation error message; sets `aria-invalid="true"` on the group\'s children.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disables the entire group.',
+    },
+    required: {
+      type: 'boolean',
+      description: "When true, marks the group's radios as required for form submission.",
+    },
+    variant: {
+      enum: ['default', 'card'],
+      description: "Visual layout. 'card' wraps each radio row in a bordered surface.",
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-radio-group`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['name'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Radio children.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/radio-group/radio-group.svelte

@@ -1,86 +1,50 @@
 <script lang="ts" module>
-  /**
-   * @cinder
-   * @category form
-   * @status stable
-   * @purpose Fieldset that owns the bound value, shared name, and validation state for a set of mutually exclusive radio children.
-   * @tag form
-   * @tag selection
-   * @useWhen Picking exactly one option from a small fixed set where every choice should stay visible.
-   * @useWhen Sharing a single error and description across a set of related radios.
-   * @avoidWhen Selecting zero or more independent options — use checkbox-group instead.
-   * @related checkbox-group
-   */
-  export type { RadioGroupContext, RadioGroupProps } from './radio-group.types.ts';
+export {};
 </script>
 
 <script lang="ts">
-  import type { RadioGroupProps } from './radio-group.types.ts';
-  import { setRadioGroupContext } from './radio-group-context.ts';
-
-  import {
-    ariaInvalid,
-    composeDescribedBy,
-    describeId,
-    errorId as buildErrorId,
-  } from '../../_internal/field-control.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import { devWarn } from '../../utilities/dev-warn.ts';
-
-  let {
-    value = $bindable(''),
-    name,
-    label: legend,
-    description,
-    error,
-    disabled = false,
-    required = false,
-    variant = 'default',
-    class: className,
-    children,
-  }: RadioGroupProps = $props();
-
-  // Group ID is needed to scope the description/error ids; consumers don't
-  // pass an id because the group itself is a fieldset, not a labelled input.
-  const groupId = $props.id();
-  const descriptionId = $derived(describeId(groupId, !!description));
-  const errId = $derived(buildErrorId(groupId, !!error));
-  const describedBy = $derived(composeDescribedBy(descriptionId, errId));
-
-  setRadioGroupContext({
+import { setRadioGroupContext } from './radio-group-context.ts';
+import { ariaInvalid, composeDescribedBy, describeId, errorId as buildErrorId, } from '../../_internal/field-control.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+let { value = $bindable(''), name, label: legend, description, error, disabled = false, required = false, variant = 'default', class: className, children, } = $props();
+// Group ID is needed to scope the description/error ids; consumers don't
+// pass an id because the group itself is a fieldset, not a labelled input.
+const groupId = $props.id();
+const descriptionId = $derived(describeId(groupId, !!description));
+const errId = $derived(buildErrorId(groupId, !!error));
+const describedBy = $derived(composeDescribedBy(descriptionId, errId));
+setRadioGroupContext({
     get name() {
-      return name;
+        return name;
     },
     get value() {
-      return value;
+        return value;
     },
     get disabled() {
-      return disabled;
+        return disabled;
     },
     get invalid() {
-      return !!error;
+        return !!error;
     },
     get required() {
-      return required;
+        return required;
     },
     select(next) {
-      value = next;
+        value = next;
     },
-  });
-
-  // Warn once when no accessible group name is provided. The `hasWarned` flag
-  // stops the effect re-firing on every `legend` change — matching the
-  // tree.svelte convention and dev-warn.ts's guidance against a warn-only
-  // effect that re-subscribes on each update.
-  let hasWarnedNoLegend = false;
-  $effect(() => {
+});
+// Warn once when no accessible group name is provided. The `hasWarned` flag
+// stops the effect re-firing on every `legend` change — matching the
+// tree.svelte convention and dev-warn.ts's guidance against a warn-only
+// effect that re-subscribes on each update.
+let hasWarnedNoLegend = false;
+$effect(() => {
     if (!legend && !hasWarnedNoLegend) {
-      hasWarnedNoLegend = true;
-      devWarn(
-        '[cinder/RadioGroup] A <fieldset> was rendered without a label prop. The fieldset will have no <legend>, which makes it inaccessible. Provide a label prop to describe the group.',
-      );
+        hasWarnedNoLegend = true;
+        devWarn('[cinder/RadioGroup] A <fieldset> was rendered without a label prop. The fieldset will have no <legend>, which makes it inaccessible. Provide a label prop to describe the group.');
     }
-  });
+});
 </script>
 
 <!--

package/src/components/radio-group/radio-group.variables.json

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

package/src/components/radio-group/radio-group.variables.ts

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

package/src/components/rating/rating.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable id used as the radio-group id prefix and as the hidden input id."
+    },
+    "value": {
+      "type": "number",
+      "description": "Bindable rating value. `0` represents an unrated state. External values\nare clamped into `[0, count]` and snapped to the nearest precision step.\n\n**No write-back normalization.** The bound prop reflects exactly what the\nconsumer set — it is NOT mutated back to the clamped/snapped value. The\ndisplayed and submitted value is normalized via `$derived`, but the binding\nitself is left untouched. This is intentional: the consumer owns the source\nof truth, and silent mutation of a bound prop is a surprising side-effect."
+    },
+    "count": {
+      "type": "number",
+      "description": "Number of rating slots. Normalized to an integer in `[1, 10]`; non-finite\nor out-of-range values fall back to `5`."
+    },
+    "precision": {
+      "enum": ["whole", "half"],
+      "description": "Precision of each step. Defaults to `'whole'`."
+    },
+    "label": {
+      "type": "string",
+      "description": "Visible group label rendered above the rating."
+    },
+    "hideLabel": {
+      "type": "boolean",
+      "description": "Visually hide the rendered `label` while keeping it programmatically associated."
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Group accessible name when no visible `label` is supplied."
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "Space-separated list of ids that label the group when no `label` is supplied."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional description text rendered below the rating."
+    },
+    "error": {
+      "type": "string",
+      "description": "Optional error message; sets `aria-invalid=\"true\"` on the rating group."
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable every rating control and the hidden input."
+    },
+    "readonly": {
+      "type": "boolean",
+      "description": "Render a non-interactive display with an accessible text equivalent."
+    },
+    "required": {
+      "type": "boolean",
+      "description": "Mark the group as required for assistive technology."
+    },
+    "name": {
+      "type": "string",
+      "description": "Form-control name applied to the hidden `<input>` that submits with the form."
+    },
+    "class": {
+      "type": "string",
+      "description": "Extra class names appended to the root group element."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["id"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "onchange",
+        "reason": "function-or-snippet",
+        "description": "Fires only for user-initiated committed value changes (click, arrow keys,\nSpace/Enter). Never fires for hover preview or external prop synchronization."
+      }
+    ]
+  }
+}

package/src/components/rating/rating.schema.ts

@@ -0,0 +1,85 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Stable id used as the radio-group id prefix and as the hidden input id.',
+    },
+    value: {
+      type: 'number',
+      description:
+        'Bindable rating value. `0` represents an unrated state. External values\nare clamped into `[0, count]` and snapped to the nearest precision step.\n\n**No write-back normalization.** The bound prop reflects exactly what the\nconsumer set — it is NOT mutated back to the clamped/snapped value. The\ndisplayed and submitted value is normalized via `$derived`, but the binding\nitself is left untouched. This is intentional: the consumer owns the source\nof truth, and silent mutation of a bound prop is a surprising side-effect.',
+    },
+    count: {
+      type: 'number',
+      description:
+        'Number of rating slots. Normalized to an integer in `[1, 10]`; non-finite\nor out-of-range values fall back to `5`.',
+    },
+    precision: {
+      enum: ['whole', 'half'],
+      description: "Precision of each step. Defaults to `'whole'`.",
+    },
+    label: {
+      type: 'string',
+      description: 'Visible group label rendered above the rating.',
+    },
+    hideLabel: {
+      type: 'boolean',
+      description:
+        'Visually hide the rendered `label` while keeping it programmatically associated.',
+    },
+    'aria-label': {
+      type: 'string',
+      description: 'Group accessible name when no visible `label` is supplied.',
+    },
+    'aria-labelledby': {
+      type: 'string',
+      description: 'Space-separated list of ids that label the group when no `label` is supplied.',
+    },
+    description: {
+      type: 'string',
+      description: 'Optional description text rendered below the rating.',
+    },
+    error: {
+      type: 'string',
+      description: 'Optional error message; sets `aria-invalid="true"` on the rating group.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disable every rating control and the hidden input.',
+    },
+    readonly: {
+      type: 'boolean',
+      description: 'Render a non-interactive display with an accessible text equivalent.',
+    },
+    required: {
+      type: 'boolean',
+      description: 'Mark the group as required for assistive technology.',
+    },
+    name: {
+      type: 'string',
+      description: 'Form-control name applied to the hidden `<input>` that submits with the form.',
+    },
+    class: {
+      type: 'string',
+      description: 'Extra class names appended to the root group element.',
+    },
+  },
+  additionalProperties: false,
+  required: ['id'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'onchange',
+        reason: 'function-or-snippet',
+        description:
+          'Fires only for user-initiated committed value changes (click, arrow keys,\nSpace/Enter). Never fires for hover preview or external prop synchronization.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;