@supersoniks/concorde 5.0.5 → 5.1.1

package/src/docs/_getting-started/components.md

@@ -0,0 +1,5 @@
+# Components
+
+Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path.
+
+<docs-components-index></docs-components-index>

package/src/docs/_getting-started/theming.md

@@ -1,4 +1,4 @@
-# Customization
+# Theming 
 
 ## Theme-first customization
 
@@ -10,7 +10,7 @@ Concorde derives radius steps, button/input rounding, shadows, and most per-comp
 
 <sonic-code language="html">
   <template>
-<sonic-theme color font class="block bg-base min-h-screen">
+<sonic-theme color font >
   <!-- your app -->
 </sonic-theme>
   </template>

package/src/docs/code.ts

@@ -7,42 +7,18 @@ import { query } from "lit/decorators/query.js";
 
 import SDUIUtils from "../core/components/functional/sdui/sdui-utils";
 
-import "./prism/prism";
-import { prismCSS } from "./prism";
-import * as Prism from "prismjs";
-import "prismjs/plugins/normalize-whitespace/prism-normalize-whitespace";
-import "prismjs/components/prism-json"; // Language
-import "prismjs/components/prism-typescript"; // Language
-import "prismjs/components/prism-javascript"; // Language
-import "prismjs/components/prism-bash"; // Language
-// import "prismjs/components/prism-css"; // Language
-import "prismjs/components/prism-markup"; // Language
-
-let normalizeWhitespaceDefaultsApplied = false;
-
-function normalizeDocsCodeLanguage(language: string): string {
-  return language === "html" ? "markup" : language;
-}
-
-function applyNormalizeWhitespaceDefaults(): void {
-  if (normalizeWhitespaceDefaultsApplied) return;
-  normalizeWhitespaceDefaultsApplied = true;
-  Prism.plugins.NormalizeWhitespace.setDefaults({
-    "remove-trailing": true,
-    "remove-indent": true,
-    "left-trim": true,
-    "right-trim": true,
-    "remove-initial-line-feed": true,
-    "tabs-to-tabs": 2,
-  });
-}
+import {
+  docsCodeCSS,
+  highlightDocsCode,
+  normalizeDocsCodeLanguage,
+} from "./shiki";
 
 const tagName = "sonic-code";
 @customElement(tagName)
 export class DocsCode extends LitElement {
   static styles = [
     tailwind,
-    prismCSS,
+    docsCodeCSS,
     css`
       :host(:not([inline])) {
         display: block;
@@ -53,11 +29,7 @@ export class DocsCode extends LitElement {
         display: inline-block;
       }
       pre {
-        font-size: 13px !important;
         padding-right: 5rem !important;
-        border: 1px solid var(--sc-base-200);
-        border-radius: var(--sc-rounded);
-        margin: 0 !important;
       }
       .custom-scroll {
         overflow: auto !important;
@@ -82,6 +54,34 @@ export class DocsCode extends LitElement {
         border-radius: var(--sc-rounded);
         border: solid 0.15rem transparent;
       }
+
+      /* Tall blocks are folded behind a fade; a click unfolds them */
+      pre.collapsible {
+        transition: max-height 0.4s ease;
+      }
+      pre.collapsible:not(.expanded) {
+        max-height: var(--docs-code-max-height, 15rem);
+        overflow-y: hidden !important;
+      }
+      pre.overflowing:not(.expanded) {
+        cursor: pointer;
+      }
+      /* fade the code only: the block keeps its background and corners */
+      pre.overflowing:not(.expanded) > code {
+        display: block;
+        /* span the longest line, or the mask would clip horizontal overflow */
+        width: max-content;
+        min-width: 100%;
+        /* fade over the last 11rem; on hover the mask slides down a little */
+        mask-image: linear-gradient(to bottom, #000 calc(100% - 11rem), transparent);
+        mask-size: 100% var(--docs-code-max-height, 20rem);
+        mask-repeat: no-repeat;
+        mask-position: 0 -2rem;
+        transition: mask-position 0.35s ease;
+      }
+      pre.overflowing:not(.expanded):hover > code {
+        mask-position: 0 0;
+      }
     `,
   ];
 
@@ -90,6 +90,8 @@ export class DocsCode extends LitElement {
   @property({ type: Boolean, reflect: true }) showCode = false;
   @property({ type: Boolean, reflect: true }) toggleCode = false;
   @property({ type: Boolean, reflect: true }) noEdit = false;
+  /** Markup shown as code only: no live preview (e.g. PHP / Vue snippets). */
+  @property({ type: Boolean, reflect: true }) noPreview = false;
 
   @property() language = "markup";
   @property({ attribute: false }) defaultCode?: string;
@@ -101,14 +103,16 @@ export class DocsCode extends LitElement {
   private templateEl: HTMLTemplateElement | null = null;
 
   @state() codeEdited = false;
+  @state() private overflowing = false;
+  @state() private expanded = false;
 
   /** Live preview only for markup (avoid injecting HTML from JS/TS examples). */
-  private get prismLanguage(): string {
+  private get highlightLanguage(): string {
     return normalizeDocsCodeLanguage(this.language);
   }
 
   private get rendersLiveOutput(): boolean {
-    return this.prismLanguage === "markup";
+    return this.highlightLanguage === "html" && !this.noPreview;
   }
 
   connectedCallback() {
@@ -128,29 +132,12 @@ export class DocsCode extends LitElement {
     }
   }
 
-  private normalizeSourceForHighlight(source: string): string {
-    applyNormalizeWhitespaceDefaults();
-    const nw = Prism.plugins.NormalizeWhitespace;
-    return nw
-      .normalize(source)
-      .replaceAll('=""', "")
-      .replaceAll(""", '"')
-      .replaceAll('"{', "'{")
-      .replaceAll('}"', "}'")
-      .replaceAll("&", "&");
-  }
-
-  private highlightSource(source: string): string {
-    const lang = this.prismLanguage;
-    const grammar = Prism.languages[lang];
-    if (!grammar) {
-      return source;
+  private async applyHighlightFromSource(source: string | undefined) {
+    if (!source) {
+      this.currentCode = undefined;
+      return;
     }
-    return Prism.highlight(
-      this.normalizeSourceForHighlight(source),
-      grammar,
-      lang,
-    );
+    this.currentCode = await highlightDocsCode(source, this.language);
   }
 
   private syncFromTemplate() {
@@ -158,11 +145,7 @@ export class DocsCode extends LitElement {
     this.defaultCode = this.readTemplateSourceCode();
     this.codeEdited = false;
 
-    if (this.defaultCode) {
-      this.currentCode = this.highlightSource(this.defaultCode);
-    } else {
-      this.currentCode = undefined;
-    }
+    void this.applyHighlightFromSource(this.defaultCode);
 
     if (this.rendersLiveOutput) {
       this.codeOutput = this.defaultCode;
@@ -175,11 +158,7 @@ export class DocsCode extends LitElement {
     this.defaultCode = this.readTemplateSourceCode();
     this.codeEdited = false;
 
-    if (this.defaultCode) {
-      this.currentCode = this.highlightSource(this.defaultCode);
-    } else {
-      this.currentCode = undefined;
-    }
+    void this.applyHighlightFromSource(this.defaultCode);
 
     if (this.rendersLiveOutput) {
       this.codeOutput = this.defaultCode;
@@ -204,7 +183,7 @@ export class DocsCode extends LitElement {
     const template = this.templateEl ?? this.querySelector("template");
     if (!template) return "";
 
-    if (this.prismLanguage === "markup") {
+    if (this.highlightLanguage === "html") {
       return this.decodeTemplateEntities(template.innerHTML);
     }
 
@@ -231,7 +210,7 @@ export class DocsCode extends LitElement {
     if (this.defaultCode) {
       this.currentCode = "";
       window.requestAnimationFrame(() => {
-        this.currentCode = this.highlightSource(this.defaultCode || "");
+        void this.applyHighlightFromSource(this.defaultCode);
       });
     }
     if (this.rendersLiveOutput) {
@@ -269,6 +248,7 @@ export class DocsCode extends LitElement {
 
   updated(changedProperties: PropertyValues) {
     super.updated(changedProperties);
+    this.measureOverflow();
     if (
       changedProperties.has("codeOutput") ||
       changedProperties.has("language")
@@ -298,12 +278,38 @@ export class DocsCode extends LitElement {
     }
   }
 
+  private measureOverflow() {
+    const pre = this.codePreview;
+    if (!pre || this.inline || this.expanded) return;
+    // Folding to hide only a few lines is just friction: show those in full.
+    if (
+      pre.scrollHeight > pre.clientHeight + 4 &&
+      pre.scrollHeight < pre.clientHeight * 1.3
+    ) {
+      this.expanded = true;
+      return;
+    }
+    const overflowing = pre.scrollHeight > pre.clientHeight + 4;
+    if (overflowing !== this.overflowing) this.overflowing = overflowing;
+  }
+
+  private expand() {
+    if (!this.overflowing || this.expanded) return;
+    const pre = this.codePreview;
+    pre.style.maxHeight = `${pre.scrollHeight}px`;
+    // Release the height once unfolded, so edited code can still grow.
+    pre.addEventListener("transitionend", () => (pre.style.maxHeight = ""), {
+      once: true,
+    });
+    this.expanded = true;
+  }
+
   handleGetSDUI() {
     SDUIUtils.toJson(this.templateEl?.content.children);
   }
 
   render() {
-    const isMarkup = this.prismLanguage === "markup";
+    const isMarkup = this.rendersLiveOutput;
 
     return html`
       <div
@@ -316,7 +322,11 @@ export class DocsCode extends LitElement {
           : nothing}
 
         <div class="relative">
-          <div class="flex justify-end absolute right-2 gap-1 mt-2">
+          <div
+            class="flex justify-end gap-1 z-10 ${this.showCode && this.currentCode
+              ? "absolute right-2 mt-2"
+              : ""}"
+          >
             ${this.codeEdited
               ? html`<sonic-button
                   size="2xs"
@@ -383,10 +393,13 @@ export class DocsCode extends LitElement {
           <div>
             <pre
               id="codePreview"
-              class="rounded-md custom-scroll language-${this.prismLanguage} ${!this
-                .showCode || !this.currentCode
+              class="rounded-md custom-scroll language-${this
+                .highlightLanguage} ${!this.showCode || !this.currentCode
                 ? "hidden"
-                : ""}"
+                : ""} ${this.inline ? "" : "collapsible"} ${this.overflowing
+                ? "overflowing"
+                : ""} ${this.expanded ? "expanded" : ""}"
+              @click=${this.expand}
               ?contenteditable=${!this.noEdit}
               spellcheck="false"
               @input=${this.updateCodeRender}

package/src/docs/components/docs-demo-sources.ts

@@ -5,10 +5,7 @@ import { tailwind } from "../tailwind";
 import { docsSourceLinks, type DocsSource } from "./docs-source-link";
 import { DOCS_SOURCE_RAW } from "./docs-source-raw";
 import { resolveSourceExcerpt } from "./docs-source-excerpt";
-import "../prism/prism";
-import { prismCSS } from "../prism";
-import * as Prism from "prismjs";
-import "prismjs/components/prism-typescript";
+import { docsCodeCSS, highlightDocsCode } from "../shiki";
 
 export type { DocsSource };
 
@@ -23,6 +20,15 @@ export type DocsLitDemoConfig = {
 };
 
 export const DOCS_LIT_DEMO_REGISTRY: Record<string, DocsLitDemoConfig> = {
+  "docs-boarding-pass-demo": {
+    sources: [
+      {
+        path: "src/docs/example/docs-boarding-pass-demo.ts",
+        line: 19,
+        label: "docs-boarding-pass-demo",
+      },
+    ],
+  },
   "docs-toggle-if-demo": {
     sources: [
       {
@@ -528,15 +534,15 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   ],
 };
 
-function highlightTs(code: string): string {
-  return Prism.highlight(code, Prism.languages.typescript, "typescript");
+function highlightTs(code: string): Promise<string> {
+  return highlightDocsCode(code, "typescript");
 }
 
 @customElement("docs-demo-sources")
 export class DocsDemoSources extends LitElement {
   static styles = [
     tailwind,
-    prismCSS,
+    docsCodeCSS,
     css`
       :host {
         display: block;
@@ -588,7 +594,9 @@ export class DocsDemoSources extends LitElement {
     const excerpt = resolveSourceExcerpt(raw, this.forTag, {
       line: primary.line,
     });
-    this.highlighted = highlightTs(excerpt);
+    void highlightTs(excerpt).then((html) => {
+      this.highlighted = html;
+    });
   }
 
   render() {

package/src/docs/components/docs-lit-demo.ts

@@ -1,5 +1,5 @@
-import { css, html, LitElement, nothing } from "lit";
-import { customElement, property, state } from "lit/decorators.js";
+import { css, html, LitElement, nothing, PropertyValues } from "lit";
+import { customElement, property } from "lit/decorators.js";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 import { tailwind } from "../tailwind";
 import { docsSourceLinks } from "./docs-source-link";
@@ -8,17 +8,8 @@ import {
   type DocsLitDemoConfig,
 } from "./docs-demo-sources";
 
-import "../prism/prism";
-import { prismCSS } from "../prism";
-import * as Prism from "prismjs";
-import "prismjs/components/prism-typescript";
-
 import { DOCS_SOURCE_RAW } from "./docs-source-raw";
-import {
-  excerptLines,
-  excerptForCustomElement,
-  resolveSourceExcerpt,
-} from "./docs-source-excerpt";
+import { excerptLines, resolveSourceExcerpt } from "./docs-source-excerpt";
 
 export { excerptForCustomElement } from "./docs-source-excerpt";
 
@@ -33,9 +24,9 @@ function resolveDemoExcerpt(
   return resolveSourceExcerpt(raw, liveTag);
 }
 
-function highlightTs(code: string): string {
-  return Prism.highlight(code, Prism.languages.typescript, "typescript");
-}
+/** Escape so tags in the TS excerpt stay text inside <template> (same as home.ts). */
+const escapeCode = (code: string) =>
+  code.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 
 const tagName = "docs-lit-demo";
 
@@ -43,21 +34,21 @@ const tagName = "docs-lit-demo";
 export class DocsLitDemo extends LitElement {
   static styles = [
     tailwind,
-    prismCSS,
     css`
       :host {
         display: block;
         margin: 1.1rem 0;
       }
-      pre {
-        font-size: 13px !important;
-      }
       .preview {
         border: 1px solid var(--sc-border, #e5e5e5);
         border-radius: 0.375rem;
         padding: 1rem;
         margin-bottom: 0.75rem;
       }
+      /* Nested sonic-code already has its own block margin */
+      sonic-code {
+        margin: 0;
+      }
     `,
   ];
 
@@ -66,16 +57,11 @@ export class DocsLitDemo extends LitElement {
 
   @property({ type: Boolean }) showCode = true;
 
-  @state() private highlighted = "";
-
-  private liveHost?: HTMLDivElement;
-
   private get config(): DocsLitDemoConfig | undefined {
     return DOCS_LIT_DEMO_REGISTRY[this.forTag];
   }
 
-  connectedCallback() {
-    super.connectedCallback();
+  private get excerpt(): string | undefined {
     const cfg = this.config;
     if (!cfg?.sources[0]) return;
 
@@ -85,32 +71,28 @@ export class DocsLitDemo extends LitElement {
       return;
     }
 
-    const liveTag = cfg.liveTag ?? this.forTag;
-    const excerpt = resolveDemoExcerpt(raw, liveTag, cfg);
-    this.highlighted = highlightTs(excerpt);
+    return resolveDemoExcerpt(raw, cfg.liveTag ?? this.forTag, cfg);
   }
 
   render() {
     const cfg = this.config;
     if (!cfg) return nothing;
 
-    const liveTag = cfg.liveTag ?? this.forTag;
+    const excerpt = this.excerpt;
 
     return html`
       ${docsSourceLinks(cfg.sources)}
       <div class="preview" data-live-host></div>
-      ${this.showCode && this.highlighted
-        ? html`
-            <pre
-              class="rounded-md custom-scroll language-typescript overflow-auto"
-            ><code>${unsafeHTML(this.highlighted)}</code></pre>
-          `
+      ${this.showCode && excerpt
+        ? unsafeHTML(
+            `<sonic-code language="typescript" noEdit noPreview><template>${escapeCode(excerpt)}</template></sonic-code>`,
+          )
         : nothing}
     `;
   }
 
-  firstUpdated() {
-    super.firstUpdated();
+  firstUpdated(_changedProperties: PropertyValues) {
+    super.firstUpdated(_changedProperties);
     this.mountLiveDemo();
   }
 

package/src/docs/docs.ts

@@ -8,6 +8,10 @@ import "./components/docs-demo-sources";
 import "./components/docs-lit-demo";
 import "./header/header";
 import "./navigation/navigation";
+import "./navigation/toc";
+import "./navigation/pager";
+import "./navigation/components-index";
+import "./home/home";
 import "./example/users";
 import "./example/docs-users-list";
 import "./example/docs-user-two-scopes";
@@ -15,6 +19,7 @@ import "./example/docs-joke-demos";
 import "./example/docs-queue-demos";
 import "./example/docs-input-autocomplete-demos";
 import "./example/docs-toggle-demos";
+import "./example/docs-boarding-pass-demo";
 import "./example/docs-list-demos";
 import "./example/docs-jsonata-demos";
 import "./example/docs-router-demos";

package/src/docs/example/docs-boarding-pass-demo.ts

@@ -0,0 +1,134 @@
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { keyed } from "lit/directives/keyed.js";
+import { subscribe } from "@supersoniks/concorde/core/decorators/Subscriber";
+import { docsBoardingPassKey } from "./docs-provider-keys";
+
+const destinations: Record<string, string> = {
+  JFK: "New York",
+  GIG: "Rio de Janeiro",
+  HND: "Tokyo",
+  DXB: "Dubai",
+  SYD: "Sydney",
+};
+
+const isChecked = (v: unknown) =>
+  v === true || v === "true" || v === 1 || v === "1";
+
+@customElement("docs-boarding-pass-demo")
+export class DocsBoardingPassDemo extends LitElement {
+  /** Light DOM: the pass is part of the page (styles in tailwind/css/docs/boarding-pass.css). */
+  createRenderRoot() {
+    return this;
+  }
+
+
+  @subscribe(docsBoardingPassKey.firstName)
+  @state()
+  firstName = "";
+
+  @subscribe(docsBoardingPassKey.lastName)
+  @state()
+  lastName = "";
+
+  @subscribe(docsBoardingPassKey.destination)
+  @state()
+  destination = "JFK";
+
+  @subscribe(docsBoardingPassKey.firstClass)
+  @state()
+  firstClass = "";
+
+  render() {
+    const first = isChecked(this.firstClass);
+    const code = this.destination || "JFK";
+    const passenger =
+      `${this.lastName || "—"} / ${this.firstName || "—"}`.toUpperCase();
+
+    return html`
+      <div class="grid gap-6 max-w-[34rem] mx-auto">
+        <div formDataProvider=${docsBoardingPassKey.path} class="grid gap-3">
+          <div class="grid gap-3 sm:grid-cols-2">
+            <sonic-input name="firstName" label="First name"></sonic-input>
+            <sonic-input name="lastName" label="Last name"></sonic-input>
+          </div>
+          <sonic-select name="destination" label="Destination">
+            ${Object.entries(destinations).map(
+              ([value, city]) =>
+                html`<option value=${value}>${city} (${value})</option>`,
+            )}
+          </sonic-select>
+          <sonic-switch name="firstClass" value="true" unique
+            >First class</sonic-switch
+          >
+        </div>
+
+        <sonic-card
+          type=${first ? "invert" : "light"}
+          shadow="none"
+          class="block relative"
+        >
+          <div class="flex items-center justify-between gap-3 mb-5">
+            <span class="font-headings italic font-semibold text-xl"
+              >concorde airways</span
+            >
+            ${keyed(
+              first,
+              html`<sonic-badge
+                class="bp-pop"
+                variant="outline"
+                type=${first ? "warning" : "default"}
+                >${first ? "First class" : "Economy"}</sonic-badge
+              >`,
+            )}
+          </div>
+
+          <div class="grid grid-cols-[auto_1fr_auto] items-center gap-3">
+            <div>
+              <div class="font-headings text-4xl sm:text-5xl leading-none">CDG</div>
+              <div class="text-xs opacity-70">Paris</div>
+            </div>
+            <div class="bp-route">
+              ${keyed(
+                code,
+                html`<sonic-icon
+                  class="bp-fly"
+                  name="plane"
+                  library="fontAwesome"
+                  prefix="solid"
+                  size="lg"
+                ></sonic-icon>`,
+              )}
+            </div>
+            <div class="text-right">
+              ${keyed(
+                code,
+                html`<div class="bp-pop font-headings text-4xl sm:text-5xl leading-none">
+                  ${code}
+                </div>`,
+              )}
+              <div class="text-xs opacity-70">${destinations[code]}</div>
+            </div>
+          </div>
+
+          <div class="grid grid-cols-3 gap-3 mt-6 text-sm">
+            <div class="col-span-3 sm:col-span-1 min-w-0">
+              <div class="text-xs opacity-60">Passenger</div>
+              <div class="font-bold truncate">${passenger}</div>
+            </div>
+            <div>
+              <div class="text-xs opacity-60">Seat</div>
+              <div class="font-bold">${first ? "1A" : "24C"}</div>
+            </div>
+            <div>
+              <div class="text-xs opacity-60">Boarding</div>
+              <div class="font-bold">${first ? "10:05" : "10:25"}</div>
+            </div>
+          </div>
+
+          <div class="bp-barcode h-10 mt-6 opacity-80"></div>
+        </sonic-card>
+      </div>
+    `;
+  }
+}

package/src/docs/example/docs-provider-keys.ts

@@ -111,6 +111,12 @@ export const docsToggleVisibilityKey = new DataProviderKey<{ togglePlan?: string
 export const docsToggleLoaderFormKey = new DataProviderKey<{ toggleLoader?: string }>(
   "toggleLoaderForm",
 );
+export const docsBoardingPassKey = new DataProviderKey<{
+  firstName?: string;
+  lastName?: string;
+  destination?: string;
+  firstClass?: string;
+}>("boardingPass");
 
 /** User / preview scopes */
 export const docsUserScopeAKey = new DataProviderKey<DocsUserData>(
@@ -222,6 +228,12 @@ export function initDocsProviderDefaults(): void {
 
   set(docsToggleVisibilityKey, { togglePlan: "true" });
   set(docsToggleLoaderFormKey, { toggleLoader: "" });
+  set(docsBoardingPassKey, {
+    firstName: "André",
+    lastName: "Turcat",
+    destination: "JFK",
+    firstClass: "true",
+  });
 
   set(docsUserScopeAKey, {
     first_name: "Paul",