@pure-ds/storybook 0.7.25 → 0.7.26

package/stories/components/PdsRating.stories.js

@@ -0,0 +1,126 @@
+import { html } from 'lit';
+
+const docsParameters = {
+  description: {
+    component: 'Form-associated star rating control with keyboard, pointer, and half-step support.'
+  }
+};
+
+if (typeof window !== 'undefined') {
+  import('../reference/reference-docs.js')
+    .then(({ createComponentDocsPage }) => {
+      docsParameters.page = createComponentDocsPage('pds-rating');
+    })
+    .catch((error) => {
+      console.warn('storybook: docs page failed to load for pds-rating', error);
+    });
+}
+
+export default {
+  title: 'Components/pds-rating',
+  tags: ['autodocs', 'rating', 'stars', 'form', 'input'],
+  parameters: {
+    pds: {
+      tags: ['rating', 'stars', 'form', 'input', 'pds-rating']
+    },
+    docs: docsParameters
+  },
+  argTypes: {
+    max: {
+      control: { type: 'number', min: 1, max: 10, step: 1 },
+      description: 'Maximum rating / star count'
+    },
+    value: {
+      control: { type: 'number', min: 0, max: 10, step: 0.5 },
+      description: 'Current rating value'
+    },
+    name: {
+      control: 'text',
+      description: 'Form field name'
+    },
+    color: {
+      control: 'text',
+      description: 'Active star color (CSS color value)'
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disable interaction and submission value'
+    },
+    required: {
+      control: 'boolean',
+      description: 'Require a value in form validation'
+    },
+    readonly: {
+      control: 'boolean',
+      description: 'Read-only but still visible value'
+    }
+  }
+};
+
+const baseTemplate = (args) => html`
+  <pds-rating
+    max="${args.max}"
+    value="${args.value}"
+    name="${args.name}"
+    color="${args.color || ''}"
+    ?disabled="${args.disabled}"
+    ?required="${args.required}"
+    ?readonly="${args.readonly}">
+  </pds-rating>
+`;
+
+export const Default = {
+  name: 'Interactive Playground',
+  render: baseTemplate,
+  args: {
+    max: 5,
+    value: 3.5,
+    name: 'rating',
+    color: '',
+    disabled: false,
+    required: false,
+    readonly: false
+  }
+};
+
+export const States = {
+  render: () => html`
+    <div class="stack-md">
+      <label class="stack-2xs">
+        <span>Default (editable)</span>
+        <pds-rating max="5" value="4" name="default-rating"></pds-rating>
+      </label>
+      <label class="stack-2xs">
+        <span>Accent color variant</span>
+        <pds-rating max="5" value="3.5" color="var(--color-accent-500)" name="color-rating"></pds-rating>
+      </label>
+      <label class="stack-2xs">
+        <span>Read-only</span>
+        <pds-rating max="5" value="2.5" readonly name="readonly-rating"></pds-rating>
+      </label>
+      <label class="stack-2xs">
+        <span>Disabled</span>
+        <pds-rating max="5" value="3" disabled name="disabled-rating"></pds-rating>
+      </label>
+    </div>
+  `
+};
+
+export const InForm = {
+  render: () => html`
+    <form id="rating-story-form" class="stack-sm" @submit="${(event) => {
+      event.preventDefault();
+      const form = event.currentTarget;
+      const data = new FormData(form);
+      const output = form.querySelector('[data-output]');
+      output.textContent = `Submitted rating: ${String(data.get('experience') ?? '(none)')}`;
+    }}">
+      <label class="stack-2xs">
+        <span>How was your experience?</span>
+        <pds-rating max="5" value="4.5" required name="experience"></pds-rating>
+      </label>
+      <button type="submit" class="btn-primary">Submit</button>
+      <p class="text-muted" data-output>Submitted rating: (none)</p>
+    </form>
+  `
+};

package/stories/components/PdsTags.stories.js

@@ -0,0 +1,224 @@
+import { html, lazyProps } from "#pds/lit";
+
+const languageOptions = [
+  { id: "et", text: "Amhaars", description: "ET · Ethiopia", category: "Languages" },
+  { id: "bd", text: "Bengaals", description: "BD · Bangladesh", category: "Languages" },
+  { id: "nl", text: "Nederlands", description: "NL · Netherlands", category: "Languages" },
+  { id: "ar", text: "Arabisch", description: "SA · Arabic", category: "Languages" },
+  { id: "bs", text: "Bosnisch", description: "BA · Bosnia and Herzegovina", category: "Languages" },
+  { id: "bg", text: "Bulgaars", description: "BG · Bulgaria", category: "Languages" },
+  { id: "fr", text: "Frans", description: "FR · France", category: "Languages" },
+  { id: "de", text: "Duits", description: "DE · Germany", category: "Languages" },
+  { id: "es", text: "Spaans", description: "ES · Spain", category: "Languages" },
+  { id: "en", text: "Engels", description: "US · United Kingdom", category: "Languages" },
+];
+
+const groupedOptions = [
+  { id: "et", text: "Amhaars", description: "ET · Ethiopia", category: "Languages" },
+  { id: "nl", text: "Nederlands", description: "NL · Netherlands", category: "Languages" },
+  { id: "react", text: "React", description: "Frontend", category: "Skills" },
+  { id: "wc", text: "Web Components", description: "Frontend", category: "Skills" },
+  { id: "figma", text: "Figma", description: "Design tooling", category: "Tools" },
+  { id: "storybook", text: "Storybook", description: "Component docs", category: "Tools" },
+];
+
+const createSettingsFromItems = (items) => {
+  const byCategory = items.reduce((map, item) => {
+    const key = item.category || "Options";
+    if (!map.has(key)) map.set(key, []);
+    map.get(key).push(item);
+    return map;
+  }, new Map());
+
+  const categories = {};
+  for (const [categoryName, entries] of byCategory.entries()) {
+    categories[categoryName] = {
+      trigger: () => true,
+      getItems: async (options) => {
+        const query = (options?.search || "").trim().toLowerCase();
+        return entries.filter((item) => {
+          if (!query) return true;
+          return (
+            item.text.toLowerCase().includes(query)
+            || item.id.toLowerCase().includes(query)
+            || (item.description || "").toLowerCase().includes(query)
+          );
+        });
+      },
+    };
+  }
+
+  return {
+    hideCategory: false,
+    categories,
+  };
+};
+
+const languageSettings = createSettingsFromItems(languageOptions);
+const groupedSettings = createSettingsFromItems(groupedOptions);
+
+const sourceCode = `<pds-tags
+  name="languages"
+  placeholder="Zoek taal..."
+  value="et,bd,nl"
+  ${"${lazyProps({ settings: languageSettings })}"}
+></pds-tags>`;
+
+const defaultDocs = {
+  description: {
+    component: "Compound multi-select built with pds-omnibox. Select/unselect values from suggestions and manage them as tags.",
+  },
+};
+
+export default {
+  title: "Components/pds-tags",
+  tags: ["autodocs", "forms", "autocomplete", "multiselect", "pds-tags"],
+  parameters: {
+    docs: defaultDocs,
+  },
+  argTypes: {
+    name: { control: "text" },
+    placeholder: { control: "text" },
+    value: { control: "text" },
+    required: { control: "boolean" },
+    disabled: { control: "boolean" },
+  },
+};
+
+const Template = ({ name, placeholder, value, required, disabled }) => html`
+  <div class="stack-md">
+    <pds-tags
+      name=${name}
+      placeholder=${placeholder}
+      value=${value}
+      ?required=${required}
+      ?disabled=${disabled}
+      ${lazyProps({ settings: languageSettings })}
+    ></pds-tags>
+  </div>
+`;
+
+const FormTemplate = ({ required }) => {
+  setTimeout(() => {
+    const form = document.querySelector("#tags-form");
+    const output = document.querySelector("#tags-output");
+    if (!form || !output || form.dataset.bound === "true") return;
+
+    form.dataset.bound = "true";
+    form.addEventListener("submit", (event) => {
+      event.preventDefault();
+      if (!form.reportValidity()) {
+        output.textContent = "Form invalid";
+        return;
+      }
+      const data = new FormData(form);
+      const languages = data.getAll("languages");
+      output.textContent = JSON.stringify({ languages }, null, 2);
+    });
+
+    form.addEventListener("reset", () => {
+      setTimeout(() => {
+        output.textContent = "{}";
+      }, 0);
+    });
+  }, 0);
+
+  return html`
+    <section class="card stack-md">
+      <h4>Form Integration</h4>
+      <form id="tags-form" class="stack-md">
+        <pds-tags
+          name="languages"
+          placeholder="Select one or more languages..."
+          ?required=${required}
+          ${lazyProps({ settings: languageSettings })}
+        ></pds-tags>
+        <div class="flex gap-sm">
+          <button class="btn-primary" type="submit">Submit</button>
+          <button class="btn-secondary" type="reset">Reset</button>
+        </div>
+      </form>
+      <pre id="tags-output" class="card surface-subtle">{}</pre>
+    </section>
+  `;
+};
+
+export const Default = {
+  args: {
+    name: "languages",
+    placeholder: "Zoek taal...",
+    value: "et,bd,nl",
+    required: false,
+    disabled: false,
+  },
+  render: Template,
+  parameters: {
+    docs: {
+      source: {
+        code: sourceCode,
+      },
+    },
+  },
+};
+
+export const Empty = {
+  args: {
+    name: "languages",
+    placeholder: "Zoek taal...",
+    value: "",
+    required: false,
+    disabled: false,
+  },
+  render: Template,
+};
+
+export const Required = {
+  args: {
+    name: "languages",
+    placeholder: "Select at least one language...",
+    value: "",
+    required: true,
+    disabled: false,
+  },
+  render: Template,
+};
+
+export const Disabled = {
+  args: {
+    name: "languages",
+    placeholder: "Zoek taal...",
+    value: "et,nl",
+    required: false,
+    disabled: true,
+  },
+  render: Template,
+};
+
+export const GroupedOptions = {
+  args: {
+    name: "selections",
+    placeholder: "Search languages, skills, or tools...",
+    value: "nl,wc,figma",
+    required: false,
+    disabled: false,
+  },
+  render: ({ name, placeholder, value, required, disabled }) => html`
+    <div class="stack-md">
+      <pds-tags
+        name=${name}
+        placeholder=${placeholder}
+        value=${value}
+        ?required=${required}
+        ?disabled=${disabled}
+        ${lazyProps({ settings: groupedSettings })}
+      ></pds-tags>
+    </div>
+  `,
+};
+
+export const FormSubmission = {
+  args: {
+    required: true,
+  },
+  render: FormTemplate,
+};

package/stories/components/PdsToaster.stories.js

@@ -70,7 +70,7 @@ export const Default = () => {
         <pds-icon icon="info" size="sm"></pds-icon>
         Info
       </button>
-      <button id="toast-warning" class="btn-warning btn-sm">
+      <button id="toast-warning" class="btn-outline btn-sm">
         <pds-icon icon="warning" size="sm"></pds-icon>
         Warning
       </button>

package/stories/components/omnibox-countries-api-settings.js

@@ -0,0 +1,63 @@
+let countryListPromise;
+
+const loadCountries = async () => {
+  if (!countryListPromise) {
+    countryListPromise = fetch("https://restcountries.com/v3.1/all?fields=name,cca2")
+      .then((res) => {
+        if (!res.ok) {
+          throw new Error(`Failed to fetch countries: ${res.status}`);
+        }
+        return res.json();
+      })
+      .then((rows) =>
+        rows
+          .map((row) => ({
+            id: row?.cca2 || row?.name?.common || "",
+            text: row?.name?.common || "",
+            icon: "globe",
+          }))
+          .filter((row) => row.id && row.text)
+          .sort((a, b) => a.text.localeCompare(b.text)),
+      );
+  }
+
+  return countryListPromise;
+};
+
+export const countriesApiSettings = {
+  hideCategory: true,
+  itemGrid: "0 1fr 0",
+  iconHandler: () => "",
+  categories: {
+    Featured: {
+      sortIndex: 2,
+      trigger: () => true,
+      getItems: async (options) => {
+        const q = (options.search || "").trim().toLowerCase();
+        const shortlist = [
+          { id: "NL", text: "Netherlands" },
+          { id: "US", text: "United States" },
+        ];
+
+        return q
+          ? shortlist.filter((item) => item.text.toLowerCase().includes(q))
+          : shortlist;
+      },
+      useIconForInput: false,
+    },
+    Countries: {
+      sortIndex: 1,
+      trigger: (options) => (options.search || "").trim().length >= 2,
+      getItems: async (options) => {
+        const q = (options.search || "").trim().toLowerCase();
+        if (!q) return [];
+
+        const countries = await loadCountries();
+        return countries
+          .filter((item) => item.text.toLowerCase().includes(q))
+          .slice(0, 30);
+      },
+      useIconForInput: false,
+    },
+  },
+};

package/stories/foundations/Colors.stories.js

@@ -267,7 +267,12 @@ export const Default = {
     return html`
       ${colorScaleStoryStyles}
       <div class="story-container color-scale-story-container">
-        <h2>Color Scales</h2>
+        <header>
+          <h3>Color Scales</h3>
+          <small class="text-muted">
+            Explore the full tokenized scales for brand and semantic colors.
+          </small>
+        </header>
         ${renderColorScale('primary')}
         ${renderColorScale('secondary')}
         ${renderColorScale('accent')}

package/stories/foundations/HTMLDefaults.stories.js

@@ -21,7 +21,7 @@ export const Overview = {
     const container = document.createElement('div');
     container.innerHTML = `
       <header >
-        <h1>HTML Defaults</h1>
+        <h3>HTML Defaults</h3>
         <small class="text-muted">
           PDS applies an opinionated reset to semantic HTML elements using low-specificity 
           <code>:where()</code> selectors. This means you get a polished, modern look out of the box, 
@@ -164,7 +164,7 @@ export const StructuralElements = {
     const container = document.createElement('div');
     container.innerHTML = `
       <header class="card">
-        <h2>Structural Elements</h2>
+        <h3>Structural Elements</h3>
         <small class="text-muted">
           Semantic containers that organize page content
         </small>
@@ -230,7 +230,7 @@ export const TextElements = {
     const container = document.createElement('div');
     container.innerHTML = `
       <header class="card">
-        <h2>Text & Quotation Elements</h2>
+        <h3>Text & Quotation Elements</h3>
         <small class="text-muted">
           Semantic text elements with automatic styling
         </small>
@@ -292,7 +292,7 @@ TextElements.storyName = 'Text Elements';
 
 export const InlineElements = () => html`
   <header class="card">
-    <h2>Inline Elements</h2>
+    <h3>Inline Elements</h3>
     <small class="text-muted">
       Small semantic elements for inline content
     </small>
@@ -347,7 +347,7 @@ export const DetailsAndSummary = {
     const container = document.createElement('div');
     container.innerHTML = `
       <header class="card">
-        <h2>Details & Summary</h2>
+        <h3>Details & Summary</h3>
         <small class="text-muted">
           Native collapsible content without JavaScript
         </small>
@@ -409,7 +409,7 @@ export const RelatedDocumentation = () => {
   container.className = 'stack gap-md';
   container.innerHTML = `
     <header class="card">
-      <h2>Related Documentation</h2>
+      <h3>Related Documentation</h3>
       <small class="text-muted">
         Detailed coverage of specific element categories
       </small>

package/stories/foundations/Icons.stories.js

@@ -78,8 +78,8 @@ export const Overview = () => {
   
   container.innerHTML = /*html*/`
     <header>
-      <h2>PDS Icon System</h2>
-      <p class="story-intro">PDS ships a simple, sprite-based icon solution and a lightweight <code>&lt;pds-icon&gt;</code> web component.</p>
+      <h3>PDS Icon System</h3>
+      <small class="text-muted story-intro">PDS ships a simple, sprite-based icon solution and a lightweight <code>&lt;pds-icon&gt;</code> web component.</small>
     </header>
 
     <section class="card">
@@ -518,7 +518,7 @@ export const AllIcons = () => {
     ${iconGridStyles}
     <section class="stack-lg story-section">
       <header>
-        <h2>All Available Icons</h2>
+        <h3>All Available Icons</h3>
         <small class="text-muted">Complete icon set from Phosphor Icons, organized by category. Click any icon name to copy it to clipboard.</small>
       </header>
 
@@ -607,7 +607,7 @@ AllIcons.storyName = 'All Icons';
 export const ExternalIcons = () => html`
   <section class="stack-lg story-section">
     <header>
-      <h2>External Icons (On-Demand Loading)</h2>
+      <h3>External Icons (On-Demand Loading)</h3>
       <small class="text-muted">
         Icons not in the sprite sheet are automatically fetched from an external path.
         This provides the best of both worlds: core icons load instantly from the cached 

package/stories/foundations/MeshGradients.stories.js

@@ -77,7 +77,7 @@ export const AllMeshGradients = () => html`
   ${meshGradientsStoryStyles}
   <section class="stack gap-lg">
     <header>
-      <h2>Mesh Gradient Backgrounds</h2>
+      <h3>Mesh Gradient Backgrounds</h3>
       <small class="text-muted">
         Subtle, beautiful mesh gradient backgrounds using
         <code>--background-mesh-01</code> through
@@ -123,7 +123,12 @@ AllMeshGradients.storyName = "All Mesh Gradients";
 export const MeshUsageExamples = () => html`
   ${meshGradientsStoryStyles}
   <section class="stack gap-lg">
-    <h2>Usage Examples</h2>
+    <header>
+      <h3>Usage Examples</h3>
+      <small class="text-muted">
+        Practical composition patterns that use mesh tokens in real UI blocks.
+      </small>
+    </header>
 
     <h3>Hero Section</h3>
     <div
@@ -211,7 +216,12 @@ export const CodeSamples = () => {
 
   container.innerHTML = /*html*/ `
     ${meshGradientsStoryStyles.strings[0]}
-    <h2>Code Samples</h2>
+    <header>
+      <h3>Code Samples</h3>
+      <small class="text-muted">
+        Copy-ready snippets and available mesh custom properties.
+      </small>
+    </header>
 
     <h3>Apply as Background</h3>
     <div class="code-css"></div>

package/stories/foundations/SmartSurfaces.stories.js

@@ -57,11 +57,13 @@ export default {
 
 export const SurfaceVariants = () => html`
   <div class="card">
-    <h2>Surface Variants</h2>
-    <p class="text-muted">
-      All surfaces automatically adjust text, icon, shadow, and border colors to
-      maintain proper contrast.
-    </p>
+    <header>
+      <h3>Surface Variants</h3>
+      <small class="text-muted">
+        All surfaces automatically adjust text, icon, shadow, and border colors
+        to maintain proper contrast.
+      </small>
+    </header>
 
     <div class="grid grid-auto-sm gap-md">
       <div class="card surface-base">
@@ -108,7 +110,7 @@ SurfaceVariants.storyName = "Surface Variants";
 export const ContextAwareShadows = () => html`
   <div>
     <header>
-      <h2>Context-Aware Shadows</h2>
+      <h3>Context-Aware Shadows</h3>
       <small class="text-muted">
         Shadows automatically invert in dark mode: dark shadows on light surfaces,
         light shadows on dark surfaces.
@@ -141,11 +143,13 @@ ContextAwareShadows.storyName = "Context-Aware Shadows";
 
 export const NestedSurfaces = () => html`
   <div class="card">
-    <h2>Nested Surfaces</h2>
-    <p class="text-muted">
-      Surfaces can be nested infinitely. Each level maintains proper contrast
-      and visual hierarchy automatically.
-    </p>
+    <header>
+      <h3>Nested Surfaces</h3>
+      <small class="text-muted">
+        Surfaces can be nested infinitely. Each level maintains proper contrast
+        and visual hierarchy automatically.
+      </small>
+    </header>
 
     <div class="card surface-base">
       <h4 class="flex items-center gap-xs">
@@ -201,11 +205,13 @@ NestedSurfaces.storyName = "Nested Surfaces";
 
 export const SurfaceInversion = () => html`
   <div class="card">
-    <h2>Surface Inversion</h2>
-    <p class="text-muted">
-      The smart surface system automatically inverts text and icon colors on
-      contrasting backgrounds. Toggle dark mode to see the magic!
-    </p>
+    <header>
+      <h3>Surface Inversion</h3>
+      <small class="text-muted">
+        The smart surface system automatically inverts text and icon colors on
+        contrasting backgrounds. Toggle dark mode to see the magic!
+      </small>
+    </header>
 
     <div class="grid grid-auto-md gap-md">
       <div class="card surface-inverse">
@@ -236,11 +242,13 @@ SurfaceInversion.storyName = "Surface Inversion";
 
 export const BorderGradients = () => html`
   <div class="card">
-    <h2>Surface Border Effects</h2>
-    <p class="text-muted">
-      Advanced border gradient effects for standout surfaces. All gradients are
-      animated and adapt to your theme.
-    </p>
+    <header>
+      <h3>Surface Border Effects</h3>
+      <small class="text-muted">
+        Advanced border gradient effects for standout surfaces. All gradients
+        are animated and adapt to your theme.
+      </small>
+    </header>
 
     <div class="grid grid-auto-md gap-lg">
       <article class="card border-gradient">
@@ -309,11 +317,13 @@ BorderGradients.storyName = "Border Gradients";
 export const TranslucentSurfaces = () => html`
   ${smartSurfacesStoryStyles}
   <div class="card">
-    <h2>Translucent Surfaces</h2>
-    <p class="text-muted">
-      Semi-transparent surfaces for glassmorphism effects and layered UI. Works
-      beautifully over images and gradients.
-    </p>
+    <header>
+      <h3>Translucent Surfaces</h3>
+      <small class="text-muted">
+        Semi-transparent surfaces for glassmorphism effects and layered UI.
+        Works beautifully over images and gradients.
+      </small>
+    </header>
 
     <div class="story-translucent-container">
       <img
@@ -355,11 +365,13 @@ TranslucentSurfaces.storyName = "Translucent Surfaces";
 
 export const SurfaceInverseExpanded = () => html`
   <div class="card">
-    <h2>Inverse Surface Deep Dive</h2>
-    <p class="text-muted">
-      The <code>.surface-inverse</code> class automatically inverts all text,
-      icon, and border colors for perfect contrast on dark backgrounds.
-    </p>
+    <header>
+      <h3>Inverse Surface Deep Dive</h3>
+      <small class="text-muted">
+        The <code>.surface-inverse</code> class automatically inverts all text,
+        icon, and border colors for perfect contrast on dark backgrounds.
+      </small>
+    </header>
 
     <div class="grid grid-auto-md gap-lg">
       <article class="card surface-inverse">