@keenmate/web-components-devkit 0.0.0-stage → 1.0.0-rc02

package/src/examples/controls-persistence.js

@@ -0,0 +1,97 @@
+/**
+ * Persist the control switches of a controls-driven example page to
+ * localStorage so the demo configuration survives a reload.
+ *
+ * Call ONCE, at the end of the page's own wiring (after the components have
+ * their data and the change-listeners are attached):
+ *
+ *     import { attachControlsPersistence } from '@keenmate/web-components-devkit/examples';
+ *     // ... build components, wire control listeners ...
+ *     attachControlsPersistence('basic');   // a stable per-page key
+ *
+ * It scans every <input>/<select> inside `.controls`, restores the saved
+ * values, then dispatches `change` (+ `input` for value controls) on each so
+ * the page's OWN listeners re-apply the configuration — no page-specific
+ * persistence code. Storage ids are namespaced by `kmwc.examples.storagePrefix`
+ * (default: the component id), so components on one origin never collide.
+ */
+import { getPageConfig } from './page-config.js';
+
+const CONTROLS_SELECTOR = '.controls input, .controls select';
+
+const getControlStateId = (control) =>
+  control.type === 'checkbox' ? `chk:${control.id}` : control.type === 'radio' ? `radio:${control.name}` : `val:${control.id}`;
+
+export function getControlsStorageKey(pageId, storagePrefix = getPageConfig().storagePrefix) {
+  return `${storagePrefix}:examples:controls:${pageId}`;
+}
+
+function getSavedControlsState(storageKey) {
+  try {
+    return JSON.parse(localStorage.getItem(storageKey) || '{}') || {};
+  } catch {
+    return {};
+  }
+}
+
+function saveControlsState(storageKey, controls) {
+  const controlsState = {};
+  for (const control of controls) {
+    if (control.type === 'radio') {
+      if (control.checked) controlsState[getControlStateId(control)] = control.value;
+    } else if (control.type === 'checkbox') {
+      controlsState[getControlStateId(control)] = control.checked;
+    } else {
+      controlsState[getControlStateId(control)] = control.value;
+    }
+  }
+  try {
+    localStorage.setItem(storageKey, JSON.stringify(controlsState));
+  } catch {
+    /* storage unavailable (private mode / quota) — degrade to no persistence */
+  }
+}
+
+/**
+ * Restore + persist all `.controls` inputs/selects under `root` for page `pageId`.
+ * @param {string} pageId stable per-page key (e.g. "basic")
+ * @param {ParentNode} [root] defaults to document
+ * @returns {{ clear(): void }} `clear()` forgets the saved state for this page
+ */
+export function attachControlsPersistence(pageId, root = document) {
+  const storageKey = getControlsStorageKey(pageId);
+  const controls = [...root.querySelectorAll(CONTROLS_SELECTOR)];
+  const persistence = { clear: () => localStorage.removeItem(storageKey) };
+  if (controls.length === 0) return persistence;
+
+  // 1) Restore saved values onto the controls.
+  const savedState = getSavedControlsState(storageKey);
+  for (const control of controls) {
+    const stateId = getControlStateId(control);
+    if (!(stateId in savedState)) continue;
+    if (control.type === 'radio') control.checked = control.value === savedState[stateId];
+    else if (control.type === 'checkbox') control.checked = !!savedState[stateId];
+    else control.value = savedState[stateId];
+  }
+
+  // 2) Re-apply through the page's own handlers. For radios fire only the
+  //    checked one per group; value controls also get `input`, since some
+  //    pages listen on that rather than `change`.
+  const firedRadioGroups = new Set();
+  for (const control of controls) {
+    if (control.type === 'radio') {
+      if (!control.checked || firedRadioGroups.has(control.name)) continue;
+      firedRadioGroups.add(control.name);
+    }
+    control.dispatchEvent(new Event('change', { bubbles: true }));
+    if (control.type !== 'radio' && control.type !== 'checkbox') control.dispatchEvent(new Event('input', { bubbles: true }));
+  }
+
+  // 3) Save on every subsequent change.
+  const handleControlChange = (event) => {
+    if (event.target?.closest?.('.controls')) saveControlsState(storageKey, controls);
+  };
+  root.addEventListener('change', handleControlChange);
+  root.addEventListener('input', handleControlChange);
+  return persistence;
+}

package/src/examples/copy-link.js

@@ -0,0 +1,89 @@
+/**
+ * COPY-LINK — a small chain-link button appended inside every section <h2>.
+ * Click copies a share-ready deep link to that section (same anchor ids as the
+ * chapter nav — both use sections.js); it briefly flips to a check + "Copied!".
+ *
+ * Link origin: the current URL by default, so on the deployed site the copied
+ * link is already public. `kmwc.examples.canonicalOrigin` (injected into the
+ * page config) forces production links even when browsing a local dev server.
+ * Styles: css/copy-link.css.
+ */
+import { ensureSectionAnchors } from './sections.js';
+import { getPageConfig } from './page-config.js';
+import { COPY_FEEDBACK_DURATION_MS, COPY_LINK_CLASSES } from './constants.js';
+
+const COPY_TITLE = 'Copy link to this section';
+
+const LINK_ICON_HTML =
+  `<svg class="${COPY_LINK_CLASSES.icon} ${COPY_LINK_CLASSES.iconLink}" viewBox="0 0 24 24" aria-hidden="true" focusable="false">` +
+  '<path d="M9 12a3 3 0 0 0 3 3h4a3 3 0 0 0 0-6h-2"></path>' +
+  '<path d="M15 12a3 3 0 0 0-3-3H8a3 3 0 0 0 0 6h2"></path>' +
+  '</svg>';
+const CHECK_ICON_HTML =
+  `<svg class="${COPY_LINK_CLASSES.icon} ${COPY_LINK_CLASSES.iconCheck}" viewBox="0 0 24 24" aria-hidden="true" focusable="false">` +
+  '<polyline points="5 13 10 18 19 7"></polyline>' +
+  '</svg>';
+
+/** Async Clipboard API (secure contexts) with an execCommand fallback. Resolves to `isCopied`. */
+export function copyText(text) {
+  if (navigator.clipboard?.writeText) {
+    return navigator.clipboard.writeText(text).then(
+      () => true,
+      () => copyTextWithExecCommand(text)
+    );
+  }
+  return Promise.resolve(copyTextWithExecCommand(text));
+}
+
+function copyTextWithExecCommand(text) {
+  try {
+    const textArea = document.createElement('textarea');
+    textArea.value = text;
+    textArea.setAttribute('readonly', '');
+    textArea.style.cssText = 'position:fixed;top:-1000px;opacity:0';
+    document.body.appendChild(textArea);
+    textArea.select();
+    const isCopied = document.execCommand('copy');
+    textArea.remove();
+    return isCopied;
+  } catch {
+    return false;
+  }
+}
+
+export function getSectionUrl(sectionId, canonicalOrigin = getPageConfig().canonicalOrigin) {
+  const baseUrl = canonicalOrigin ? canonicalOrigin.replace(/\/$/, '') + location.pathname : location.href;
+  return `${baseUrl.replace(/#.*$/, '')}#${sectionId}`;
+}
+
+function createCopyLinkButton(sectionId) {
+  const button = document.createElement('button');
+  button.type = 'button';
+  button.className = COPY_LINK_CLASSES.root;
+  button.setAttribute('aria-label', COPY_TITLE);
+  button.title = COPY_TITLE;
+  button.innerHTML = `${LINK_ICON_HTML}${CHECK_ICON_HTML}<span class="${COPY_LINK_CLASSES.label}" aria-hidden="true">Copied!</span>`;
+
+  let revertTimer = null;
+  button.addEventListener('click', (event) => {
+    event.preventDefault();
+    copyText(getSectionUrl(sectionId)).then((isCopied) => {
+      button.classList.toggle(COPY_LINK_CLASSES.rootCopied, isCopied);
+      button.classList.toggle(COPY_LINK_CLASSES.rootFailed, !isCopied);
+      button.title = isCopied ? 'Link copied!' : 'Press Ctrl/Cmd+C to copy';
+      clearTimeout(revertTimer);
+      revertTimer = setTimeout(() => {
+        button.classList.remove(COPY_LINK_CLASSES.rootCopied, COPY_LINK_CLASSES.rootFailed);
+        button.title = COPY_TITLE;
+      }, COPY_FEEDBACK_DURATION_MS);
+    });
+  });
+  return button;
+}
+
+/** Append a copy-link button to every section heading that doesn't have one yet. */
+export function attachCopyLinks() {
+  for (const section of ensureSectionAnchors()) {
+    if (!section.heading.querySelector(`.${COPY_LINK_CLASSES.root}`)) section.heading.appendChild(createCopyLinkButton(section.id));
+  }
+}

package/src/examples/css/base.css

@@ -0,0 +1,215 @@
+/* ==============================================================================
+   EXAMPLES KIT — BASE
+   ==============================================================================
+   Reset, page layout, header, cards/sections, typography, links, footer. */
+@layer kmwc {
+    /* ==========================================================================
+       RESET & PAGE
+       ========================================================================== */
+    * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+    }
+
+    html {
+        scroll-behavior: smooth;
+    }
+
+    body {
+        font-family: var(--kmwc-font-family);
+        padding: 2rem;
+        background: var(--kmwc-page-bg);
+        color: var(--kmwc-text-color-1);
+        line-height: 1.6;
+    }
+
+    .container {
+        max-width: var(--kmwc-max-width);
+        margin: 0 auto;
+    }
+
+    /* ==========================================================================
+       HEADER
+       ========================================================================== */
+    header {
+        background: var(--kmwc-header-bg);
+        color: var(--kmwc-text-color-on-accent);
+        padding: 2rem;
+        border-radius: var(--kmwc-radius-lg);
+        margin-bottom: 2rem;
+        box-shadow: 0 4px 6px var(--kmwc-shadow-color);
+    }
+
+    h1 {
+        font-size: 2.5rem;
+        margin-bottom: 0.5rem;
+    }
+
+    .subtitle {
+        opacity: 0.9;
+        font-size: 1.1rem;
+    }
+
+    .back-link {
+        display: inline-block;
+        color: var(--kmwc-text-color-on-accent);
+        text-decoration: none;
+        margin-bottom: 1rem;
+        opacity: 0.8;
+        transition: opacity 0.2s;
+    }
+
+    .back-link:hover {
+        opacity: 1;
+        text-decoration: none;
+    }
+
+    /* ==========================================================================
+       CARDS / SECTIONS
+       ==========================================================================
+       Each `.card` / `.example-section` led by an <h2> is a chapter for the
+       chapter nav and gets a copy-link button. */
+    .card,
+    .example-section {
+        background: var(--kmwc-main-bg);
+        border-radius: var(--kmwc-radius-lg);
+        padding: 2rem;
+        margin-bottom: 2rem;
+        box-shadow: 0 2px 4px var(--kmwc-shadow-color);
+        /* Headroom for hash-jumps from the chapter nav / copied links. */
+        scroll-margin-top: 1rem;
+    }
+
+    .card h2,
+    .example-section h2 {
+        margin-bottom: 1rem;
+        color: var(--kmwc-text-color-1);
+        font-size: 1.5rem;
+        /* Flex so an inline `.badge` / copy-link sits centered by the text;
+           wrap so headings mixing text and <code> chips flow onto new lines. */
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 0.5rem;
+    }
+
+    .card h3,
+    .example-section h3 {
+        margin-bottom: 0.75rem;
+        color: var(--kmwc-text-color-2);
+        font-size: 1.25rem;
+    }
+
+    .card h3.subsection,
+    .example-section h3.subsection {
+        margin: 2rem 0 1rem;
+        font-size: 1.2rem;
+        color: var(--kmwc-accent-color);
+    }
+
+    .card p,
+    .example-section p {
+        margin-bottom: 1rem;
+        color: var(--kmwc-text-color-2);
+    }
+
+    /* Demo card — a padded box framing one demo instance (lighter than `.card`).
+       Surface tunable via `--demo-card-bg` / `--demo-card-border`. */
+    .demo-card {
+        background: var(--demo-card-bg, var(--kmwc-main-bg));
+        border: var(--demo-card-border, 1px solid var(--kmwc-border-color));
+        border-radius: var(--kmwc-radius-md);
+        padding: 1.5rem;
+    }
+
+    .demo-card h3,
+    .demo-card h4 {
+        margin: 0 0 0.5rem 0;
+        font-size: 1rem;
+        color: var(--kmwc-text-color-1);
+        border: none;
+        padding: 0;
+    }
+
+    .demo-card p {
+        margin: 0 0 1rem 0;
+        font-size: 0.8125rem;
+        color: var(--kmwc-text-color-3);
+    }
+
+    .demo-card code {
+        padding: 0.125rem 0.375rem;
+        font-size: 0.7rem;
+    }
+
+    .description {
+        color: var(--kmwc-text-color-3);
+        margin-bottom: 1.5rem;
+    }
+
+    /* ==========================================================================
+       TYPOGRAPHY, LINKS, FOOTER
+       ========================================================================== */
+    h2 {
+        color: var(--kmwc-text-color-1);
+        margin-bottom: 1rem;
+    }
+
+    h3 {
+        color: var(--kmwc-text-color-2);
+        margin-bottom: 0.75rem;
+    }
+
+    ul {
+        line-height: 1.8;
+    }
+
+    li {
+        color: var(--kmwc-text-color-2);
+    }
+
+    a {
+        color: var(--kmwc-accent-color);
+        text-decoration: none;
+    }
+
+    a:hover {
+        text-decoration: underline;
+    }
+
+    footer {
+        text-align: center;
+        padding: 2rem;
+        color: var(--kmwc-text-color-3);
+        font-size: 0.875rem;
+    }
+
+    footer a {
+        color: var(--kmwc-accent-color);
+    }
+
+    /* ==========================================================================
+       RESPONSIVE & MOTION
+       ========================================================================== */
+    @media (max-width: 768px) {
+        body {
+            padding: 1rem;
+        }
+
+        h1 {
+            font-size: 2rem;
+        }
+
+        .card,
+        .example-section {
+            padding: 1.5rem;
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        html {
+            scroll-behavior: auto;
+        }
+    }
+}

package/src/examples/css/chapter-nav.css

@@ -0,0 +1,179 @@
+/* ==============================================================================
+   EXAMPLES KIT — CHAPTER NAV
+   ==============================================================================
+   Floating "on this page" navigator (chapter-nav.js): a grab tab pinned to the
+   right edge ~1/3 down; the panel is positioned against it by Floating UI. */
+@layer kmwc {
+    /* ==========================================================================
+       TAB
+       ========================================================================== */
+    .kmwc-chapter-nav {
+        position: fixed;
+        top: 33vh;
+        right: 0;
+        z-index: 9000;
+        pointer-events: none; /* clicks fall through; children re-enable */
+    }
+
+    .kmwc-chapter-nav__panel,
+    .kmwc-chapter-nav__toggle {
+        pointer-events: auto;
+    }
+
+    .kmwc-chapter-nav__toggle {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 44px;
+        height: 48px;
+        padding: 0;
+        background: var(--kmwc-accent-color);
+        color: var(--kmwc-text-color-on-accent);
+        border: none;
+        border-radius: 10px 0 0 10px;
+        box-shadow: 0 6px 18px var(--kmwc-accent-shadow-color);
+        cursor: pointer;
+        transition: background 0.2s, box-shadow 0.2s;
+    }
+
+    .kmwc-chapter-nav__toggle:hover {
+        background: var(--kmwc-accent-color-hover);
+    }
+
+    .kmwc-chapter-nav--open .kmwc-chapter-nav__toggle {
+        background: var(--kmwc-accent-color-active);
+    }
+
+    .kmwc-chapter-nav__toggle svg {
+        width: 22px;
+        height: 22px;
+        fill: none;
+        stroke: currentColor;
+        stroke-width: 2;
+        stroke-linecap: round;
+    }
+
+    .kmwc-chapter-nav__toggle svg circle {
+        fill: currentColor;
+        stroke: none;
+    }
+
+    /* ==========================================================================
+       PANEL
+       ==========================================================================
+       Hidden (and non-interactive) until open; left/top set inline by
+       Floating UI. */
+    .kmwc-chapter-nav__panel {
+        position: fixed;
+        z-index: 9000;
+        width: 260px;
+        max-width: 72vw;
+        max-height: 60vh;
+        overflow-y: auto;
+        overscroll-behavior: contain;
+        background: var(--kmwc-main-bg);
+        border: 1px solid var(--kmwc-border-color);
+        border-radius: 10px;
+        box-shadow: 0 20px 25px -5px var(--kmwc-shadow-color), 0 8px 10px -6px var(--kmwc-shadow-color);
+        padding: 0.5rem;
+        opacity: 0;
+        visibility: hidden;
+        transform: translateX(8px);
+        transition: opacity 0.18s ease, transform 0.18s ease, visibility 0.18s;
+    }
+
+    .kmwc-chapter-nav--open .kmwc-chapter-nav__panel {
+        opacity: 1;
+        visibility: visible;
+        transform: translateX(0);
+    }
+
+    .kmwc-chapter-nav__back {
+        display: block;
+        margin-bottom: 0.35rem;
+        padding: 0.45rem 0.6rem;
+        border-radius: var(--kmwc-radius-sm);
+        font-size: 0.82rem;
+        font-weight: 600;
+        color: var(--kmwc-accent-color);
+        text-decoration: none;
+        background: var(--kmwc-accent-light-bg);
+        transition: background 0.15s;
+    }
+
+    .kmwc-chapter-nav__back:hover {
+        background: var(--kmwc-accent-light-bg-hover);
+        text-decoration: none;
+    }
+
+    .kmwc-chapter-nav__title {
+        font-size: 0.72rem;
+        font-weight: 700;
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+        color: var(--kmwc-text-color-4);
+        padding: 0.25rem 0.5rem 0.4rem;
+    }
+
+    .kmwc-chapter-nav__list {
+        list-style: none;
+        margin: 0;
+        padding: 0;
+    }
+
+    .kmwc-chapter-nav__item {
+        display: block;
+        padding: 0.4rem 0.6rem;
+        border-radius: var(--kmwc-radius-sm);
+        border-left: 3px solid transparent;
+        font-size: 0.85rem;
+        line-height: 1.35;
+        color: var(--kmwc-text-color-2);
+        text-decoration: none;
+        transition: background 0.15s, color 0.15s, border-color 0.15s;
+    }
+
+    .kmwc-chapter-nav__item:hover {
+        background: var(--kmwc-hover-bg);
+        color: var(--kmwc-text-color-1);
+        text-decoration: none;
+    }
+
+    .kmwc-chapter-nav__item--active {
+        background: var(--kmwc-accent-light-bg);
+        color: var(--kmwc-accent-color);
+        border-left-color: var(--kmwc-accent-color);
+        font-weight: 600;
+    }
+
+    /* ==========================================================================
+       RESPONSIVE & MOTION
+       ========================================================================== */
+    @media (max-width: 768px) {
+        .kmwc-chapter-nav__panel {
+            width: 80vw;
+            max-width: 80vw;
+            max-height: 80vh;
+        }
+
+        .kmwc-chapter-nav__title {
+            font-size: 0.9rem;
+        }
+
+        .kmwc-chapter-nav__item {
+            font-size: 1.05rem;
+            padding: 0.7rem 0.85rem;
+        }
+
+        .kmwc-chapter-nav__toggle {
+            width: 40px;
+            height: 44px;
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        .kmwc-chapter-nav__panel {
+            transition: none;
+        }
+    }
+}