@supersoniks/concorde 5.0.5 → 5.1.1

package/src/docs/header/header.ts

@@ -1,4 +1,4 @@
-import { html, LitElement, nothing } from "lit";
+import { css, html, LitElement, nothing } from "lit";
 import { customElement, state } from "lit/decorators.js";
 import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
 import { tailwind } from "../tailwind";
@@ -7,11 +7,95 @@ import { Theme } from "@supersoniks/concorde/core/components/ui/theme/theme";
 const tagName = "sonic-docs-header"; // For Astro.build
 @customElement(tagName)
 export class SonicComponent extends Subscriber(LitElement) {
-  static styles = [tailwind];
+  static styles = [
+    tailwind,
+    css`
+      /* paint the page gutters too, so content never shows beside the sticky bar */
+      .header-bar {
+        box-shadow:
+          -5rem 0 0 var(--sc-base),
+          5rem 0 0 var(--sc-base);
+      }
+      /* the rule under the bar runs on through the gutters, edge to edge */
+      .header-bar::after {
+        content: "";
+        position: absolute;
+        left: 0;
+        right: 0;
+        bottom: -0.18rem;
+        height: 0.18rem;
+        background: currentColor;
+        box-shadow:
+          -5rem 0 0 currentColor,
+          5rem 0 0 currentColor;
+      }
+      .logo-plane path {
+        transform-box: view-box;
+        transform-origin: 33px 33px;
+        /* takes off every 6s (flight in the first ~1.1s, then parked) */
+        animation: takeoff 6s cubic-bezier(0.5, 0, 0.3, 1) 0.5s infinite;
+      }
+      .logo:hover .logo-plane path,
+      .logo:focus-visible .logo-plane path {
+        animation: takeoff-again 1.1s cubic-bezier(0.5, 0, 0.3, 1);
+      }
+      @keyframes takeoff-again {
+        12% {
+          transform: translateY(3px);
+        }
+        50% {
+          transform: translateY(-64px) scale(0.85);
+        }
+        50.01% {
+          transform: translateY(64px) scale(0.85);
+        }
+      }
+      @keyframes takeoff {
+        0% {
+          transform: translateY(0);
+        }
+        2% {
+          transform: translateY(3px);
+        }
+        9% {
+          transform: translateY(-64px) scale(0.85);
+        }
+        9.01% {
+          transform: translateY(64px) scale(0.85);
+        }
+        18%,
+        100% {
+          transform: translateY(0);
+        }
+      }
+      @media (prefers-reduced-motion: reduce) {
+        .logo-plane path,
+        .logo:hover .logo-plane path {
+          animation: none;
+        }
+      }
+    `,
+  ];
 
   @state() theme: "dark" | "light" = "light";
   @state() searchVisible = false;
 
+  /** Publishes the bar's height as --docs-header-h so sticky panels sit right under it. */
+  private headerResize = new ResizeObserver(([entry]) => {
+    const h = Math.round(entry.target.getBoundingClientRect().height);
+    document.documentElement.style.setProperty("--docs-header-h", `${h}px`);
+  });
+
+  firstUpdated() {
+    const bar = this.shadowRoot?.querySelector(".header-bar");
+    if (bar) this.headerResize.observe(bar);
+  }
+
+  disconnectedCallback() {
+    this.headerResize.disconnect();
+    super.disconnectedCallback();
+  }
+
   connectedCallback() {
     this.handleColorScheme();
     super.connectedCallback();
@@ -36,9 +120,10 @@ export class SonicComponent extends Subscriber(LitElement) {
       }
     });
 
-    // on hash change, hide search
+    // on hash change, hide search and mobile navigation
     window.addEventListener("hashchange", () => {
       this.hideSearch();
+      this.closeNavigation();
     });
   }
 
@@ -63,6 +148,17 @@ export class SonicComponent extends Subscriber(LitElement) {
     this.handleColorScheme();
   }
 
+  openNavigation() {
+    this.shadowRoot
+      ?.querySelector<HTMLElement & { show(): void }>("#mobile-nav")
+      ?.show();
+  }
+  closeNavigation() {
+    this.shadowRoot
+      ?.querySelector<HTMLElement & { hide(): void }>("#mobile-nav")
+      ?.hide();
+  }
+
   hideSearch() {
     this.searchVisible = false;
   }
@@ -72,12 +168,22 @@ export class SonicComponent extends Subscriber(LitElement) {
 
   render() {
     return html`<div
-        class="flex items-center gap-4 border-b-[.18rem]  text-content border-current py-3 sticky top-0 z-40  bg-neutral-0"
+        class="flex items-center gap-2 sm:gap-4 border-b-[.18rem] text-content border-current py-3 sticky top-0 z-40 bg-neutral-0 header-bar"
       >
-        <div class="">
-          <sonic-link href="/" class="flex items-end gap-x-1">
+        <sonic-button
+          class="lg:hidden"
+          shape="circle"
+          variant="ghost"
+          icon
+          data-aria-label="Open navigation"
+          @click=${() => this.openNavigation()}
+        >
+          <sonic-icon name="menu" library="iconoir"></sonic-icon>
+        </sonic-button>
+        <div class="min-w-0">
+          <sonic-link href="/" class="logo flex items-end gap-x-1">
             <svg
-              class="size-[2.4rem] inline-block  rotate-[55deg] "
+              class="size-8 sm:size-[2.4rem] inline-block rotate-[55deg]"
               viewBox="0 0 66 66"
               fill="none"
               xmlns="http://www.w3.org/2000/svg"
@@ -88,47 +194,60 @@ export class SonicComponent extends Subscriber(LitElement) {
                 r="30"
                 fill="var(--sc-base-content, #000)"
               />
-              <path
-                d="M33.2499 62.03C33.8799 59.24 34.26 56.17 34.39 53.08C34.57 52.78 34.9099 52.6 35.2599 52.64H35.39C35.48 52.64 35.5799 52.64 35.6899 52.64H35.7599C35.7599 52.64 35.7999 52.64 35.8299 52.64C36.2499 52.62 36.6799 52.58 36.9099 52.56C36.9399 52.56 36.9599 52.56 36.9799 52.56C37.0099 52.56 37.0299 52.56 37.0499 52.56H37.0899L37.2099 51.93H37.4799L37.5799 52.4L37.6899 52.49H39.2699L39.39 52.38L39.5099 51.93H39.7899L39.8399 52.21L39.9999 52.29L45.2099 51.86L46.2799 51.29C46.2799 51.29 46.2799 50.85 46.2399 50.25V50.18C46.2399 50.18 46.2399 50.13 46.2399 50.11C46.2099 49.62 46.1399 49.13 46.0399 48.65C45.7899 47.45 45.29 46 42.2 41.58C39.11 37.16 38.04 35.52 35.89 27.63C35.85 27.48 35.8199 27.35 35.7899 27.2C35.1399 24.53 34.6899 22.95 34.5199 22.38V10.89C34.4999 9.60996 34.3999 8.33996 34.2099 7.07996C34.0499 5.97996 33.6099 4.89996 33.3499 3.95996H32.6299C32.3599 4.89996 31.9299 5.97996 31.7699 7.06996C31.5799 8.33996 31.4799 9.60996 31.4599 10.89V22.38C31.2899 22.95 30.8299 24.52 30.1899 27.2C30.1599 27.35 30.1199 27.49 30.0899 27.63C27.9499 35.52 26.8699 37.16 23.7799 41.58C20.6899 46 20.1899 47.45 19.9399 48.65C19.8399 49.13 19.7799 49.62 19.7399 50.11C19.7399 50.13 19.7399 50.16 19.7399 50.18V50.25C19.6999 50.85 19.7 51.29 19.7 51.29L20.7699 51.86L25.9799 52.29L26.14 52.21L26.1899 51.93H26.4799L26.5999 52.38L26.7299 52.49H28.2999L28.4099 52.4L28.5099 51.93H28.7699L28.89 52.56H28.9399C28.9399 52.56 28.9799 52.56 29.0099 52.56C29.0299 52.56 29.0499 52.56 29.0799 52.56C29.3099 52.58 29.7499 52.63 30.1599 52.64C30.1799 52.64 30.2099 52.64 30.2299 52.64H30.2999C30.4099 52.64 30.5099 52.64 30.5999 52.64H30.7299C31.0799 52.6 31.4299 52.77 31.6099 53.08C31.7299 56.17 32.1099 59.24 32.7399 62.03H33.2499Z"
-                fill="var(--sc-base, #fff)"
-              />
+              <clipPath id="logo-circle">
+                <circle cx="33" cy="33" r="30" />
+              </clipPath>
+              <g class="logo-plane" clip-path="url(#logo-circle)">
+                <path
+                  d="M33.2499 62.03C33.8799 59.24 34.26 56.17 34.39 53.08C34.57 52.78 34.9099 52.6 35.2599 52.64H35.39C35.48 52.64 35.5799 52.64 35.6899 52.64H35.7599C35.7599 52.64 35.7999 52.64 35.8299 52.64C36.2499 52.62 36.6799 52.58 36.9099 52.56C36.9399 52.56 36.9599 52.56 36.9799 52.56C37.0099 52.56 37.0299 52.56 37.0499 52.56H37.0899L37.2099 51.93H37.4799L37.5799 52.4L37.6899 52.49H39.2699L39.39 52.38L39.5099 51.93H39.7899L39.8399 52.21L39.9999 52.29L45.2099 51.86L46.2799 51.29C46.2799 51.29 46.2799 50.85 46.2399 50.25V50.18C46.2399 50.18 46.2399 50.13 46.2399 50.11C46.2099 49.62 46.1399 49.13 46.0399 48.65C45.7899 47.45 45.29 46 42.2 41.58C39.11 37.16 38.04 35.52 35.89 27.63C35.85 27.48 35.8199 27.35 35.7899 27.2C35.1399 24.53 34.6899 22.95 34.5199 22.38V10.89C34.4999 9.60996 34.3999 8.33996 34.2099 7.07996C34.0499 5.97996 33.6099 4.89996 33.3499 3.95996H32.6299C32.3599 4.89996 31.9299 5.97996 31.7699 7.06996C31.5799 8.33996 31.4799 9.60996 31.4599 10.89V22.38C31.2899 22.95 30.8299 24.52 30.1899 27.2C30.1599 27.35 30.1199 27.49 30.0899 27.63C27.9499 35.52 26.8699 37.16 23.7799 41.58C20.6899 46 20.1899 47.45 19.9399 48.65C19.8399 49.13 19.7799 49.62 19.7399 50.11C19.7399 50.13 19.7399 50.16 19.7399 50.18V50.25C19.6999 50.85 19.7 51.29 19.7 51.29L20.7699 51.86L25.9799 52.29L26.14 52.21L26.1899 51.93H26.4799L26.5999 52.38L26.7299 52.49H28.2999L28.4099 52.4L28.5099 51.93H28.7699L28.89 52.56H28.9399C28.9399 52.56 28.9799 52.56 29.0099 52.56C29.0299 52.56 29.0499 52.56 29.0799 52.56C29.3099 52.58 29.7499 52.63 30.1599 52.64C30.1799 52.64 30.2099 52.64 30.2299 52.64H30.2999C30.4099 52.64 30.5099 52.64 30.5999 52.64H30.7299C31.0799 52.6 31.4299 52.77 31.6099 53.08C31.7299 56.17 32.1099 59.24 32.7399 62.03H33.2499Z"
+                  fill="var(--sc-base, #fff)"
+                />
+              </g>
             </svg>
 
             <span
-              class="font-headings text-4xl leading-none inline-block italic font-semibold"
+              class="font-headings text-3xl sm:text-4xl leading-none inline-block italic font-semibold"
               >concorde</span
             >
           </sonic-link>
         </div>
 
-        <div class="ml-auto flex gap-x-3 ">
+        <div class="ml-auto flex items-center gap-x-1 sm:gap-x-3">
           <sonic-button
-            class="lg:hidden"
-            shape="circle"
-            icon
-            @click=${() => (this.searchVisible = !this.searchVisible)}
+            class="hidden md:block"
+            variant="ghost"
+            size="sm"
+            href="#docs/_getting-started/start.md/start"
+            >Docs</sonic-button
           >
-            <sonic-icon name="magnifying-glass" library="custom"></sonic-icon>
-          </sonic-button>
           <sonic-button
-            @click=${() => (this.searchVisible = !this.searchVisible)}
-            class="hidden lg:block lg:w-[19rem]"
-            shape="block"
-            align="left"
+            class="hidden md:block"
+            variant="ghost"
+            size="sm"
+            href="#docs/_getting-started/components.md/components"
+            >Components</sonic-button
+          >
+          <sonic-button
+            variant="ghost"
+            shape="circle"
+            icon
+            target="_blank"
+            data-aria-label="npm package"
+            href="https://www.npmjs.com/package/@supersoniks/concorde"
           >
-            Search...
             <sonic-icon
-              name="magnifying-glass"
-              library="custom"
-              slot="prefix"
+              name="npm"
+              library="fontAwesome"
+              prefix="brands"
             ></sonic-icon>
           </sonic-button>
-
           <sonic-pop>
             <sonic-button shape="circle" variant="ghost" icon>
-              ${this.theme == "light"
-                ? html`<sonic-icon name="sun" library="custom"></sonic-icon>`
-                : html`<sonic-icon name="moon" library="custom"></sonic-icon>`}
+              ${
+                this.theme == "light"
+                  ? html`<sonic-icon name="sun" library="custom"></sonic-icon>`
+                  : html`<sonic-icon name="moon" library="custom"></sonic-icon>`
+              }
             </sonic-button>
 
             <sonic-menu slot="content">
@@ -156,67 +275,112 @@ export class SonicComponent extends Subscriber(LitElement) {
               </sonic-menu-item>
             </sonic-menu>
           </sonic-pop>
+          <sonic-button
+            class="lg:hidden"
+            shape="circle"
+            variant="ghost"
+            icon
+            @click=${() => (this.searchVisible = !this.searchVisible)}
+          >
+            <sonic-icon name="magnifying-glass" library="custom"></sonic-icon>
+          </sonic-button>
+          <sonic-button
+            @click=${() => (this.searchVisible = !this.searchVisible)}
+            class="hidden lg:block lg:w-[19rem]"
+            shape="block"
+            align="left"
+          >
+            Search...
+            <sonic-icon
+              name="magnifying-glass"
+              library="custom"
+              slot="prefix"
+            ></sonic-icon>
+          </sonic-button>
         </div>
       </div>
 
-      ${this.searchVisible
-        ? html`
-            <div
-              ${animate({
-                keyframeOptions: {
-                  duration: 250,
-                },
-                in: [
-                  {
-                    opacity: 0,
-                  },
-                ],
-                out: [
-                  {
-                    opacity: 0,
-                  },
-                ],
-                stabilizeOut: true,
-              })}
-              class="fixed top-0 w-full left-0  z-[3000] pt-[20vh] flex items-center justify-center "
-            >
-              <div
-                @click=${() => this.hideSearch()}
-                class="bg-neutral-0 dark:bg-neutral-300 opacity-90 fixed top-0 left-0 w-full h-full "
-              ></div>
+      <sonic-modal
+        id="mobile-nav"
+        effect="fade"
+        maxWidth="min(92vw, 22rem)"
+        maxHeight="88vh"
+        closeOnLocationChange
+      >
+        <sonic-modal-title>Documentation</sonic-modal-title>
+        <sonic-modal-content>
+          <docs-navigation
+            class="block"
+            @click=${(e: Event) => {
+              const onItem = e
+                .composedPath()
+                .some((n) => (n as HTMLElement).tagName === "SONIC-MENU-ITEM");
+              if (onItem) this.closeNavigation();
+            }}
+          ></docs-navigation>
+        </sonic-modal-content>
+      </sonic-modal>
 
+      ${
+        this.searchVisible
+          ? html`
               <div
                 ${animate({
                   keyframeOptions: {
                     duration: 250,
-                    easing: `cubic-bezier(0.250, 0.250, 0.420, 1.225)`,
                   },
                   in: [
                     {
-                      transform: "translateY(1rem) scale(1.05)",
                       opacity: 0,
                     },
                   ],
                   out: [
                     {
-                      transform: "scale(.90) ",
                       opacity: 0,
-                      duration: 3000,
-                      easing: `ease-in-out`,
                     },
                   ],
                   stabilizeOut: true,
                 })}
-                class="relative z-20 max-w-[30rem] lg:max-w-[35rem] w-full block   "
+                class="fixed top-0 w-full left-0  z-[3000] pt-[20vh] flex items-center justify-center "
               >
-                <docs-search
-                  setFocus
-                  class="max-w-[30rem] lg:max-w-[35rem] w-full block"
+                <div
+                  @click=${() => this.hideSearch()}
+                  class="bg-neutral-0 dark:bg-neutral-300 opacity-90 fixed top-0 left-0 w-full h-full "
+                ></div>
+
+                <div
+                  ${animate({
+                    keyframeOptions: {
+                      duration: 250,
+                      easing: `cubic-bezier(0.250, 0.250, 0.420, 1.225)`,
+                    },
+                    in: [
+                      {
+                        transform: "translateY(1rem) scale(1.05)",
+                        opacity: 0,
+                      },
+                    ],
+                    out: [
+                      {
+                        transform: "scale(.90) ",
+                        opacity: 0,
+                        duration: 3000,
+                        easing: `ease-in-out`,
+                      },
+                    ],
+                    stabilizeOut: true,
+                  })}
+                  class="relative z-20 max-w-[30rem] lg:max-w-[35rem] w-full block   "
                 >
-                </docs-search>
+                  <docs-search
+                    setFocus
+                    class="max-w-[30rem] lg:max-w-[35rem] w-full block"
+                  >
+                  </docs-search>
+                </div>
               </div>
-            </div>
-          `
-        : nothing}`;
+            `
+          : nothing
+      }`;
   }
 }

package/src/docs/home/catalog.ts

@@ -0,0 +1,44 @@
+/** One-line notes for the home index, keyed by sidebar label (taken from each component page). */
+export const COMPONENT_NOTES: Record<string, { tag: string; note: string }> = {
+  Alert: { tag: "sonic-alert", note: "Inline feedback: errors, confirmations, contextual help." },
+  Badge: { tag: "sonic-badge", note: "Compact label for a status, a count or a category." },
+  Button: { tag: "sonic-button", note: "Action or link, with types, variants, sizes and loading." },
+  Captcha: { tag: "sonic-captcha", note: "ALTCHA widget wired to the surrounding form data." },
+  Card: { tag: "sonic-card", note: "Groups related content on a padded, themed surface." },
+  Checkbox: { tag: "sonic-checkbox", note: "Boolean or multi-value field that publishes to a form." },
+  Divider: { tag: "sonic-divider", note: "Horizontal or vertical separator, with an optional label." },
+  Fieldset: { tag: "sonic-fieldset", note: "Groups related controls under a legend." },
+  "Form actions": { tag: "sonic-form-actions", note: "Lays out submit, cancel and other form footer controls." },
+  "Form layout": { tag: "sonic-form-layout", note: "Responsive grid for form fields with steady spacing." },
+  Group: { tag: "sonic-group", note: "Joins buttons, inputs and selects into one row." },
+  Icon: { tag: "sonic-icon", note: "Inline SVG icons from the core set or a CDN library." },
+  Image: { tag: "sonic-image", note: "Responsive image with ratio, cover fit and load transition." },
+  Input: { tag: "sonic-input", note: "Text field that publishes its value to a form provider." },
+  "Input autocomplete": { tag: "sonic-input-autocomplete", note: "Field with suggestions fed by a queue." },
+  Link: { tag: "sonic-link", note: "Navigation for routes, anchors and external URLs." },
+  Loader: { tag: "sonic-loader", note: "Loading animation, inline or as an overlay." },
+  Menu: { tag: "sonic-menu", note: "Row or column of menu items for navigation or actions." },
+  Modal: { tag: "sonic-modal", note: "Dialog overlay with title, content and actions." },
+  Pop: { tag: "sonic-pop", note: "Floating panel anchored to a trigger." },
+  Progress: { tag: "sonic-progress", note: "Completion bar on a value and max scale, or indeterminate." },
+  Radio: { tag: "sonic-radio", note: "One choice among several, published to a form." },
+  Select: { tag: "sonic-select", note: "Drop-down choice that publishes to a form." },
+  Switch: { tag: "sonic-switch", note: "On and off toggle that publishes to a form." },
+  Table: { tag: "sonic-table", note: "Tabular data from composable rows and cells." },
+  Textarea: { tag: "sonic-textarea", note: "Multi-line text field for forms." },
+  Theme: { tag: "sonic-theme", note: "Registers the design tokens and wraps the app." },
+  Toast: { tag: "sonic-toast", note: "Short-lived feedback in a fixed stack." },
+  Tooltip: { tag: "sonic-tooltip", note: "Short label on hover and focus." },
+  Date: { tag: "sonic-date", note: "Formats dates and durations, localised." },
+  Fetch: { tag: "sonic-fetch", note: "Loads an endpoint into a data provider." },
+  If: { tag: "sonic-if", note: "Shows its content while a condition holds." },
+  List: { tag: "sonic-list", note: "Renders a fetched collection with a template." },
+  Mix: { tag: "sonic-mix", note: "Merges several data providers into one." },
+  Jsonata: { tag: "sonic-jsonata", note: "Transforms data with a JSONata expression." },
+  Queue: { tag: "sonic-queue", note: "Paginated, lazy-loaded lists, page after page." },
+  Router: { tag: "sonic-router", note: "Renders the view that matches the location." },
+  SDUI: { tag: "sonic-sdui", note: "Builds an interface from a JSON descriptor." },
+  States: { tag: "sonic-states", note: "Switches content on a data value or a pattern." },
+  Submit: { tag: "sonic-submit", note: "Sends a form provider to an API endpoint." },
+  Value: { tag: "sonic-value", note: "Prints a live value from a data provider." },
+};