@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/secret-value-field/secret-value-field.svelte

@@ -0,0 +1,195 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { onDestroy, untrack } from 'svelte';
+import { copyToClipboard } from '../../utilities/clipboard.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import VisuallyHiddenLiveRegion from '../_visually-hidden-live-region.svelte';
+let { value, prefix, suffix, label = 'Secret value', allowReveal = false, initiallyRevealed = false, confirmDuration = 1500, copiedLabel = 'Copied', warning, class: className, ...rest } = $props();
+const fieldId = $props.id();
+let revealed = $state(untrack(() => initiallyRevealed));
+let previousValue = $state(untrack(() => value));
+let copied = $state(false);
+let resetTimer;
+const copiedAnnouncement = $derived(copied ? copiedLabel : '');
+// The mask string never leaks the real value — it is always a fixed character sequence.
+const MASK = '••••••••••••••••';
+async function handleCopy() {
+    const ok = await copyToClipboard(value);
+    if (!ok)
+        return;
+    copied = true;
+    if (resetTimer)
+        clearTimeout(resetTimer);
+    resetTimer = setTimeout(() => {
+        copied = false;
+    }, confirmDuration);
+}
+function handleRevealToggle() {
+    if (!allowReveal)
+        return;
+    revealed = !revealed;
+}
+$effect(() => {
+    if (value === previousValue)
+        return;
+    previousValue = value;
+    revealed = initiallyRevealed;
+});
+onDestroy(() => {
+    if (resetTimer)
+        clearTimeout(resetTimer);
+});
+</script>
+
+<!--
+  Security contract:
+  - The `value` prop is NEVER placed in title, aria-label, data-*, or any passive attribute.
+  - The masked display uses a fixed bullet string; the real value only appears in the
+    visible text when `initiallyRevealed` is true or when the user explicitly requests
+    reveal AND `allowReveal` is true.
+  - After a successful copy, no visible text exposes the value — only the live-region
+    announcement ("Copied") fires, and that text never contains the secret.
+  - The copy button aria-label names the field, not the value.
+-->
+<div
+  {...rest}
+  class={classNames('cinder-secret-value-field', className)}
+  data-cinder-copied={copied || undefined}
+  data-cinder-revealed={revealed || undefined}
+>
+  <!-- Field label -->
+  <span id={fieldId} class="cinder-secret-value-field__label">{label}</span>
+
+  <!-- Value display row -->
+  <div class="cinder-secret-value-field__row" role="group" aria-labelledby={fieldId}>
+    <!-- Prefix metadata (e.g. "example_live_") — does not contain the secret -->
+    {#if prefix}
+      <span class="cinder-secret-value-field__prefix" aria-hidden="true">{prefix}</span>
+    {/if}
+
+    <!-- Masked/revealed value display.
+         Security: the aria-label names the region state ("masked" or "revealed")
+         but does NOT contain the secret value itself. -->
+    <span
+      class="cinder-secret-value-field__value"
+      aria-label={revealed ? `${label}, revealed` : `${label}, masked`}
+      data-cinder-masked={!revealed || undefined}>{revealed ? value : MASK}</span
+    >
+
+    <!-- Suffix metadata (e.g. last 4 chars) — does not contain the secret -->
+    {#if suffix}
+      <span class="cinder-secret-value-field__suffix" aria-hidden="true">{suffix}</span>
+    {/if}
+
+    <!-- Action buttons -->
+    <div class="cinder-secret-value-field__actions">
+      <!-- Reveal/hide toggle — only rendered when allowReveal is true -->
+      {#if allowReveal}
+        <button
+          type="button"
+          class="cinder-secret-value-field__toggle"
+          aria-pressed={revealed}
+          aria-label={revealed ? `Hide ${label}` : `Reveal ${label}`}
+          onclick={handleRevealToggle}
+        >
+          {#if revealed}
+            <!-- Eye-slash icon: hide -->
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 20 20"
+              fill="currentColor"
+              class="cinder-secret-value-field__icon"
+              aria-hidden="true"
+            >
+              <path
+                fill-rule="evenodd"
+                d="M3.28 2.22a.75.75 0 00-1.06 1.06l14.5 14.5a.75.75 0 101.06-1.06l-1.745-1.745a10.029 10.029 0 003.3-4.38 1.651 1.651 0 000-1.185A10.004 10.004 0 009.999 3a9.956 9.956 0 00-4.744 1.194L3.28 2.22zM7.752 6.69l1.092 1.092a2.5 2.5 0 013.374 3.373l1.091 1.092a4 4 0 00-5.557-5.557z"
+                clip-rule="evenodd"
+              />
+              <path
+                d="M10.748 13.93l2.523 2.524a9.987 9.987 0 01-3.27.547c-4.258 0-7.894-2.66-9.337-6.41a1.651 1.651 0 010-1.186A10.007 10.007 0 012.839 6.02L6.07 9.252a4 4 0 004.678 4.678z"
+              />
+            </svg>
+          {:else}
+            <!-- Eye icon: reveal -->
+            <svg
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 20 20"
+              fill="currentColor"
+              class="cinder-secret-value-field__icon"
+              aria-hidden="true"
+            >
+              <path d="M10 12.5a2.5 2.5 0 100-5 2.5 2.5 0 000 5z" />
+              <path
+                fill-rule="evenodd"
+                d="M.664 10.59a1.651 1.651 0 010-1.186A10.004 10.004 0 0110 3c4.257 0 7.893 2.66 9.336 6.41.147.381.146.804 0 1.186A10.004 10.004 0 0110 17c-4.257 0-7.893-2.66-9.336-6.41zM14 10a4 4 0 11-8 0 4 4 0 018 0z"
+                clip-rule="evenodd"
+              />
+            </svg>
+          {/if}
+        </button>
+      {/if}
+
+      <!-- Copy button.
+           Security: aria-label is stable ("Copy {label}") and never changes after copy.
+           A11y: the success confirmation is announced exclusively via the live region below —
+           NOT by changing the button's accessible name. Changing the name on copy double-announces
+           (the AT reads the new name as a live-region change AND as the button name on next focus)
+           and conflicts with the button role. This mirrors CopyButton's canonical model. -->
+      <button
+        type="button"
+        class="cinder-secret-value-field__copy"
+        aria-label={`Copy ${label}`}
+        data-cinder-copied={copied || undefined}
+        onclick={handleCopy}
+      >
+        {#if copied}
+          <!-- Checkmark icon -->
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            class="cinder-secret-value-field__icon"
+            aria-hidden="true"
+          >
+            <path
+              fill-rule="evenodd"
+              d="M16.704 4.153a.75.75 0 01.143 1.052l-8 10.5a.75.75 0 01-1.127.075l-4.5-4.5a.75.75 0 011.06-1.06l3.894 3.893 7.48-9.817a.75.75 0 011.05-.143z"
+              clip-rule="evenodd"
+            />
+          </svg>
+        {:else}
+          <!-- Copy icon -->
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+            class="cinder-secret-value-field__icon"
+            aria-hidden="true"
+          >
+            <path
+              d="M7 3.5A1.5 1.5 0 018.5 2h3.879a1.5 1.5 0 011.06.44l3.122 3.12A1.5 1.5 0 0117 6.622V12.5a1.5 1.5 0 01-1.5 1.5h-1v-3.379a3 3 0 00-.879-2.121L10.5 5.379A3 3 0 008.379 4.5H7v-1z"
+            />
+            <path
+              d="M4.5 6A1.5 1.5 0 003 7.5v9A1.5 1.5 0 004.5 18h7a1.5 1.5 0 001.5-1.5v-5.879a1.5 1.5 0 00-.44-1.06L9.44 6.439A1.5 1.5 0 008.378 6H4.5z"
+            />
+          </svg>
+        {/if}
+      </button>
+    </div>
+  </div>
+
+  <!-- Warning/help content slot: e.g. "Copy this now; it will not be shown again." -->
+  {#if warning}
+    <div class="cinder-secret-value-field__warning">
+      {@render warning()}
+    </div>
+  {/if}
+
+  <!-- Polite live region: announces "Copied" after a successful copy.
+       The announcement text never contains the secret itself. -->
+  <VisuallyHiddenLiveRegion message={copiedAnnouncement} />
+</div>

package/src/components/secret-value-field/secret-value-field.types.ts

@@ -0,0 +1,47 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/**
+ * Props for the SecretValueField component.
+ *
+ * Displays a masked secret value (API key, token, webhook secret) with an
+ * accessible copy action. The secret is never rendered into passive attributes
+ * like `title`, `aria-label`, or `data-*`. Reveal is opt-in and off by default.
+ */
+export type SecretValueFieldProps = Omit<HTMLAttributes<HTMLDivElement>, 'class' | 'children'> & {
+  /** The secret value to copy. Never rendered in attributes or visible text post-copy. Required. */
+  value: string;
+
+  /** Visible prefix shown before the masked region (e.g. `example_live_`). Does not contain the secret. */
+  prefix?: string;
+
+  /** Visible suffix shown after the masked region (e.g. last 4 chars "a3f9"). Does not contain the secret. */
+  suffix?: string;
+
+  /** Accessible label for the field and copy button region. Defaults to "Secret value". */
+  label?: string;
+
+  /** When true, allows the user to reveal/hide the full secret. Opt-in; false by default for security. */
+  allowReveal?: boolean;
+
+  /**
+   * Shows the full unmasked value on initial render. This is an explicit
+   * one-time reveal for the "secret was just created, copy it now" flow and is
+   * INDEPENDENT of `allowReveal`: it does not add a reveal/hide toggle, it just
+   * starts unmasked. Only set this when the surrounding UI makes the one-time
+   * exposure intentional (e.g. a "copy your new key" panel).
+   */
+  initiallyRevealed?: boolean;
+
+  /** Duration in milliseconds to show the copy confirmation state. Default 1500. */
+  confirmDuration?: number;
+
+  /** Accessible label announced after a successful copy. Defaults to "Copied". */
+  copiedLabel?: string;
+
+  /** Optional advisory content rendered below the field (e.g. "Copy this now; it will not be shown again"). */
+  warning?: Snippet;
+
+  /** Additional CSS classes applied to the root element. */
+  class?: string;
+};

package/src/components/secret-value-field/secret-value-field.variables.ts

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

package/src/components/section-heading/index.ts

@@ -0,0 +1,6 @@
+import './section-heading.css';
+import SectionHeading from './section-heading.svelte';
+
+export default SectionHeading;
+export type { SectionHeadingLevel, SectionHeadingProps } from './section-heading.types.ts';
+export { SectionHeading };

package/src/components/section-heading/section-heading.schema.ts

@@ -0,0 +1,52 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    title: {
+      type: 'string',
+      description: 'Section title text. Rendered inside the dynamic heading element.',
+    },
+    description: {
+      type: 'string',
+      description:
+        'Optional supporting description. Supplementary body text, not a heading\n subtitle — rendered after the heading but outside `<hgroup>`.',
+    },
+    level: {
+      enum: [2, 3, 4],
+      description:
+        "Heading level for the title element. Defaults to `2`. The correct level\n relative to the surrounding document outline is the consumer's responsibility.",
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged onto the root `<div>`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['title'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'actions',
+        reason: 'function-or-snippet',
+        description:
+          'Optional trailing actions (buttons, menus). Rendered on the same row\n as the title at wide viewports.',
+      },
+      {
+        name: 'label',
+        reason: 'function-or-snippet',
+        description:
+          'Optional small uppercase "eyebrow" label. When present, the label is\n rendered as a `<p>` inside an `<hgroup>` that also contains the heading.\n\n The `<hgroup>` content model only permits `<p>` elements plus one\n heading element, so the snippet **must render phrasing content only** —\n plain text, `<span>`, `<strong>`, `<em>`, `<a>`, icons, etc. Do not\n render block elements (`<div>`, `<nav>`, `<button>` wrappers, additional\n headings) into this snippet; doing so produces invalid HTML inside\n `<hgroup>`.',
+      },
+      {
+        name: 'tabs',
+        reason: 'function-or-snippet',
+        description:
+          'Optional tablist. When both `actions` and `tabs` are present, `tabs`\n sits on a second row inside the shared root container.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/section-heading/section-heading.svelte

@@ -0,0 +1,40 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+let { title, description, level = 2, class: className, label, actions, tabs, } = $props();
+const headingTag = $derived(`h${level}`);
+</script>
+
+<div
+  class={classNames('cinder-section-heading', className)}
+  data-cinder-variant={actions && tabs ? 'actions-and-tabs' : undefined}
+>
+  <div class="cinder-section-heading__row">
+    <div class="cinder-section-heading__primary">
+      {#if label}
+        <hgroup class="cinder-section-heading__hgroup">
+          <p class="cinder-section-heading__label">{@render label()}</p>
+          <svelte:element this={headingTag} class="cinder-section-heading__title"
+            >{title}</svelte:element
+          >
+        </hgroup>
+      {:else}
+        <svelte:element this={headingTag} class="cinder-section-heading__title"
+          >{title}</svelte:element
+        >
+      {/if}
+      {#if description}
+        <p class="cinder-section-heading__description">{description}</p>
+      {/if}
+    </div>
+    {#if actions}
+      <div class="cinder-section-heading__actions">{@render actions()}</div>
+    {/if}
+  </div>
+  {#if tabs}
+    <div class="cinder-section-heading__tabs">{@render tabs()}</div>
+  {/if}
+</div>

package/src/components/section-heading/section-heading.types.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+/** Heading level for the rendered section title. Sections nest, so this is
+ *  the consumer's responsibility — there is no sensible global default beyond
+ *  `2`, which suits a single-level section inside an `<h1>` page.
+ *
+ *  Deeper levels (`5`, `6`) are intentionally excluded: this primitive targets
+ *  top-level section headers in page bodies, and very deep nesting usually
+ *  signals a structural problem. Expand the union additively if needed later. */
+export type SectionHeadingLevel = 2 | 3 | 4;
+export type SectionHeadingProps = {
+  /** Section title text. Rendered inside the dynamic heading element. */
+  title: string;
+  /** Optional supporting description. Supplementary body text, not a heading
+   *  subtitle — rendered after the heading but outside `<hgroup>`. */
+  description?: string;
+  /** Heading level for the title element. Defaults to `2`. The correct level
+   *  relative to the surrounding document outline is the consumer's responsibility. */
+  level?: SectionHeadingLevel;
+  /** Additional class names merged onto the root `<div>`. */
+  class?: string;
+  /** Optional small uppercase "eyebrow" label. When present, the label is
+   *  rendered as a `<p>` inside an `<hgroup>` that also contains the heading.
+   *
+   *  The `<hgroup>` content model only permits `<p>` elements plus one
+   *  heading element, so the snippet **must render phrasing content only** —
+   *  plain text, `<span>`, `<strong>`, `<em>`, `<a>`, icons, etc. Do not
+   *  render block elements (`<div>`, `<nav>`, `<button>` wrappers, additional
+   *  headings) into this snippet; doing so produces invalid HTML inside
+   *  `<hgroup>`. */
+  label?: Snippet;
+  /** Optional trailing actions (buttons, menus). Rendered on the same row
+   *  as the title at wide viewports. */
+  actions?: Snippet;
+  /** Optional tablist. When both `actions` and `tabs` are present, `tabs`
+   *  sits on a second row inside the shared root container. */
+  tabs?: Snippet;
+};

package/src/components/section-heading/section-heading.variables.ts

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

package/src/components/segment/index.ts

@@ -0,0 +1,5 @@
+import Segment from './segment.svelte';
+
+export default Segment;
+export type { SegmentProps } from './segment.types.ts';
+export { Segment };

package/src/components/segment/segment.schema.ts

@@ -0,0 +1,50 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    class: {
+      type: 'string',
+      description: 'Custom class merged with `.cinder-segmented-control-option`.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disable just this segment (independent of the control-level `disabled`).',
+    },
+    controls: {
+      type: 'string',
+      description:
+        'ID of the panel this segment controls — only meaningful when the parent\n`SegmentedControl` uses `variant="tablist"`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: "The segment's label content.",
+      },
+      {
+        name: 'leading',
+        reason: 'function-or-snippet',
+        description: 'Optional decorative content rendered before the label, inside `aria-hidden`.',
+      },
+      {
+        name: 'trailing',
+        reason: 'function-or-snippet',
+        description: 'Optional decorative content rendered after the label, inside `aria-hidden`.',
+      },
+      {
+        name: 'value',
+        reason: 'unknown-shape',
+        required: true,
+        description: 'Value this segment represents. Must be unique within the parent control.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/segment/segment.svelte

@@ -0,0 +1,73 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { untrack } from 'svelte';
+import { classNames } from '../../utilities/class-names.ts';
+import { getSegmentedControlContext } from '../segmented-control/segmented-control-state.svelte.ts';
+let { value, disabled = false, controls, leading, trailing, children, class: customClassName, ...rest } = $props();
+const context = getSegmentedControlContext();
+const registerSegment = (node) => {
+    // Attachments run inside a tracked effect. Wrap the call to register() in
+    // `untrack` so the controller's mutation of its internal state does not
+    // re-arm this attachment, which would otherwise unregister + re-register
+    // on every render and starve the reactivity graph. The registration
+    // object exposes props via getters so prop changes flow live to consumers
+    // without needing to re-register.
+    return untrack(() => context.register({
+        node,
+        get value() {
+            return value;
+        },
+        get disabled() {
+            return disabled || context.controlDisabled;
+        },
+        get controls() {
+            return controls;
+        },
+    }));
+};
+const isSelected = $derived(context.isSelected(value));
+const isFocusable = $derived(context.isFocusable(value));
+const effectiveDisabled = $derived(disabled || context.controlDisabled);
+const role = $derived(context.selectionMode === 'multiple'
+    ? undefined
+    : context.variant === 'tablist'
+        ? 'tab'
+        : 'radio');
+</script>
+
+<button
+  {...rest}
+  type="button"
+  {role}
+  data-cinder-segment-value={value}
+  aria-checked={role === 'radio' ? isSelected : undefined}
+  aria-selected={role === 'tab' ? isSelected : undefined}
+  aria-pressed={context.selectionMode === 'multiple' ? isSelected : undefined}
+  aria-controls={role === 'tab' ? controls : undefined}
+  aria-disabled={effectiveDisabled ? 'true' : undefined}
+  disabled={context.selectionMode === 'multiple' ? effectiveDisabled : undefined}
+  tabindex={isFocusable ? 0 : -1}
+  class={classNames('cinder-segmented-control-option', customClassName)}
+  data-cinder-selected={isSelected ? '' : undefined}
+  data-cinder-pressed={context.selectionMode === 'multiple' && isSelected ? '' : undefined}
+  onclick={() => context.toggle(value)}
+  {@attach registerSegment}
+>
+  {#if leading}
+    <span class="cinder-segmented-control-option-icon" aria-hidden="true">
+      {@render leading()}
+    </span>
+  {/if}
+  <!-- children: Snippet is required in TypeScript but the optional-chain is a
+     JS-caller safety net. Segment requires SegmentedControl's group context to
+     render so it can't be tested standalone; the guard is verified at code level. -->
+  {@render children?.()}
+  {#if trailing}
+    <span class="cinder-segmented-control-option-trailing" aria-hidden="true">
+      {@render trailing()}
+    </span>
+  {/if}
+</button>

package/src/components/segment/segment.types.ts

@@ -0,0 +1,39 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+
+// Attributes the component owns and computes itself, so a consumer value would
+// be silently overridden. `onfocus` / `onblur` are intentionally NOT here: the
+// component implements no focus handling, so forwarding them through `...rest`
+// lets consumers wire focus-driven behavior (tooltips, analytics) on a segment.
+type SegmentOwnedAttributes =
+  | 'role'
+  | 'type'
+  | 'disabled'
+  | 'tabindex'
+  | 'class'
+  | 'aria-checked'
+  | 'aria-selected'
+  | 'aria-pressed'
+  | 'aria-controls'
+  | 'aria-disabled'
+  | 'onclick';
+
+export type SegmentProps = Omit<HTMLButtonAttributes, SegmentOwnedAttributes> & {
+  /** Value this segment represents. Must be unique within the parent control. */
+  value: string;
+  /** Custom class merged with `.cinder-segmented-control-option`. */
+  class?: string | undefined;
+  /** Disable just this segment (independent of the control-level `disabled`). */
+  disabled?: boolean | undefined;
+  /**
+   * ID of the panel this segment controls — only meaningful when the parent
+   * `SegmentedControl` uses `variant="tablist"`.
+   */
+  controls?: string | undefined;
+  /** Optional decorative content rendered before the label, inside `aria-hidden`. */
+  leading?: Snippet | undefined;
+  /** Optional decorative content rendered after the label, inside `aria-hidden`. */
+  trailing?: Snippet | undefined;
+  /** The segment's label content. */
+  children: Snippet;
+};

package/src/components/segment/segment.variables.ts

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

package/src/components/segmented-control/index.ts

@@ -0,0 +1,8 @@
+import Segment from '../segment/segment.svelte';
+import './segmented-control.css';
+import SegmentedControl from './segmented-control.svelte';
+
+export default SegmentedControl;
+export type { SegmentProps } from '../segment/segment.types.ts';
+export type { SegmentedControlProps } from './segmented-control.types.ts';
+export { Segment, SegmentedControl };