@supersoniks/concorde 5.1.1 → 5.1.2

package/src/docs/search/markdown-renderer.ts

@@ -16,7 +16,24 @@ export class DocsMakdownRenderer extends Subscriber(LitElement) {
     marked.use(gfmHeadingId());
     this.noShadowDom = "";
     super.connectedCallback();
+    this.addEventListener("click", this.onDocLinkClick);
   }
+
+  disconnectedCallback() {
+    this.removeEventListener("click", this.onDocLinkClick);
+    super.disconnectedCallback();
+  }
+
+  /** Markdown `[…](/docs/…)` links use plain `<a>` — pushState so the SPA does not full-reload. */
+  private onDocLinkClick = (e: Event) => {
+    const a = (e.target as Element | null)?.closest?.("a");
+    if (!a || a.target === "_blank" || a.hasAttribute("download")) return;
+    const href = a.getAttribute("href");
+    if (!href || href.startsWith("http") || href.startsWith("mailto:")) return;
+    if (!(href.startsWith("/docs/") || href.startsWith("/core/"))) return;
+    e.preventDefault();
+    history.pushState(null, "", href);
+  };
   @property() anchor = "";
   private _text = "";
   set text(value: string) {
@@ -45,16 +62,17 @@ export class DocsMakdownRenderer extends Subscriber(LitElement) {
   appendImport() {
     if (this.querySelector("h1 + sonic-code")) return;
 
-    const locationHash = document.location.hash;
-    // Only real component pages (core/components/…), not any URL mentioning "components"
-    const isComponent = parseDocsLocation(locationHash).url.startsWith(
-      "core/components/",
+    const { url } = parseDocsLocation(
+      document.location.pathname + document.location.search + document.location.hash,
     );
+    // Only real component pages (core/components/…), not any URL mentioning "components"
+    const isComponent = url.startsWith("core/components/");
 
     if (isComponent) {
-      const split = locationHash.split("/");
-      const componentName = split.filter((name) => name.endsWith(".md")).pop();
-      const extractComponentName = componentName?.replace(".md", "");
+      const extractComponentName = url
+        .split("/")
+        .pop()
+        ?.replace(/\.mdx?$/, "");
 
       const markup = `<sonic-code language="javascript" class="mb-8"
       ><template> import '@supersoniks/concorde/${extractComponentName}'; </template>

package/src/docs/search/page.ts

@@ -8,12 +8,15 @@ const tagName = "docs-page"; // For Astro.build
 @customElement(tagName)
 export class DocsPage extends Subscriber(LitElement) {
   connectedCallback() {
-    this.setAttribute(
-      "serviceURL",
-      document.location.pathname.replace(/\/index.html$/, "")
-    );
-    this.markDownsURL = this.getAncestorAttributeValue("markDownsURL");
-    if (this.markDownsURL.lastIndexOf("/") != this.markDownsURL.length - 1) {
+    // Markdown is at the public pathname + `.md` (e.g. `/docs/…/start.md`).
+    // Fetch from site root via API serviceURL = origin; never relative to the
+    // current pushState path.
+    this.setAttribute("serviceURL", "");
+    this.markDownsURL = this.getAncestorAttributeValue("markDownsURL") || "";
+    if (
+      this.markDownsURL &&
+      this.markDownsURL.lastIndexOf("/") != this.markDownsURL.length - 1
+    ) {
       this.markDownsURL += "/";
     }
     super.connectedCallback();

package/src/docs/search/search.ts

@@ -1,95 +1,151 @@
-import { html, LitElement, nothing } from "lit";
+import { css, html, LitElement, nothing } from "lit";
 import { customElement, state, property } from "lit/decorators.js";
 import { PublisherManager } from "@supersoniks/concorde/utils";
 import { tailwind } from "../tailwind";
 import search from "./docs-search.json";
 import "@supersoniks/concorde/core/components/ui/divider/divider";
 import "@supersoniks/concorde/core/components/ui/icon/icon";
-import "@supersoniks/concorde/core/components/ui/menu/menu";
+import "@supersoniks/concorde/core/components/ui/menu/menu-item";
 import "@supersoniks/concorde/core/components/ui/pop/pop";
 import { customScroll } from "@supersoniks/concorde/core/components/ui/_css/scroll";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
 
 import { FormElementInterface } from "@supersoniks/concorde/core/mixins/FormElement";
 import { Pop } from "@supersoniks/concorde/core/components/ui/pop/pop";
+import { docsPagePath } from "../docs-location";
+
+type SearchItem = { href: string; part: string; search: string; index: number };
+type SearchGroup = { title: string; href: string | null; items: SearchItem[] };
+
+/** Max sections listed under each page, and characters shown around a match. */
+const MAX_ITEMS_PER_PAGE = 3;
+const SNIPPET_RADIUS = 60;
 
 const tagName = "docs-search"; // For Astro.build
 const win: any = window;
 const fuzzysort = win.fuzzysort;
 @customElement(tagName)
 export class DocsSearch extends LitElement {
-  static styles = [tailwind, customScroll];
+  static styles = [
+    tailwind,
+    customScroll,
+    css`
+      .snippet mark {
+        background: none;
+        color: var(--sc-info);
+        font-weight: 600;
+      }
+    `,
+  ];
   @state({ type: Boolean }) hidePopMenu = false;
+  @state() results: SearchGroup[] = [];
+  @state() query = "";
   @property({ type: Boolean }) setFocus = false;
   search(val) {
-    // if (!val || val.length < 3) {
-    //   this.hidePopMenu = true;
-    //   return null;
-    // } else this.hidePopMenu = false;
-    PublisherManager.get("searchSelection").selection = null;
-    const searchResult = fuzzysort.go(val, search, { key: "search" });
-    const resultForList: Array<any> = [];
-    const titlesToContent: Map<string, any> = new Map();
+    this.query = (val ?? "").toString();
+    if (!this.query.trim()) {
+      this.results = [];
+      (this.shadowRoot?.querySelector("sonic-pop") as Pop)?.show();
+      return;
+    }
+    const searchResult = fuzzysort.go(this.query, search, {
+      key: "search",
+      limit: 60,
+    });
+    const groups: Map<string, SearchGroup> = new Map();
+    const found = new Set<string>();
 
-    const found: Array<string> = [];
     for (const result of searchResult) {
       if (result.score < -100000) continue;
-
       const obj = result.obj;
-
       for (const file in obj.files) {
         for (const part in obj.files[file].hashes) {
+          if (found.has(file + ":" + part)) continue;
+          found.add(file + ":" + part);
           const hash = obj.files[file].hashes[part];
-          if (found.includes(file + ":" + part)) continue;
-          found.push(file + ":" + part);
           const title = obj.files[file].title;
-          const subItem = {
-            href: "#" + file + "/" + part,
-            part: hash.title || "...",
-            search:
-              hash.type == "page" ? "Page" : this.getResultSearchString(result),
-            index: search.indexOf(obj),
-            template: hash.type == "page" ? "page" : null,
-          };
-          if (!titlesToContent.has(title)) {
-            const item: any = {
-              title: title,
-              items: [subItem],
-            };
-            titlesToContent.set(title, item);
-            resultForList.push(item);
-          } else {
-            const item = titlesToContent.get(title);
-            item.items.push(subItem);
+          // file is e.g. docs/getting-started/start.md — public pathname routes
+          const publicPath = docsPagePath(file);
+          const baseName = publicPath.split("/").pop() || "";
+          const href =
+            hash.type === "page" || part === baseName
+              ? publicPath
+              : `${publicPath}#${part}`;
+          let group = groups.get(title);
+          if (!group) {
+            group = { title, href: null, items: [] };
+            groups.set(title, group);
+          }
+          if (hash.type == "page") {
+            group.href = href;
+            continue;
           }
+          group.items.push({
+            href,
+            part: hash.title || title,
+            search: this.getResultSearchString(result),
+            index: search.indexOf(obj),
+          });
         }
       }
     }
-    (this.shadowRoot?.querySelector("sonic-pop") as Pop)?.show();
-    // this.hidePopMenu = resultForList.length == 0;
-    for (const item of resultForList) {
-      item.items.sort((a, b) => a.index - b.index);
+    for (const group of groups.values()) {
+      group.items.sort((a, b) => a.index - b.index);
+      group.items = group.items.slice(0, MAX_ITEMS_PER_PAGE);
+      group.href ??= group.items[0]?.href ?? null;
     }
-    PublisherManager.get("searchResult").set(resultForList);
+    this.results = [...groups.values()];
+    (this.shadowRoot?.querySelector("sonic-pop") as Pop)?.show();
   }
+
+  /**
+   * Close the header search overlay after choosing a result.
+   * Capture phase: menu-item pushState calls stopPropagation on bubble.
+   * pushState itself does not fire popstate, so the header cannot rely on that.
+   */
+  private closeAfterNavigate = (e: Event) => {
+    const item = e.composedPath().find((n): n is HTMLElement => {
+      if (!(n instanceof HTMLElement) || n.tagName !== "SONIC-MENU-ITEM") {
+        return false;
+      }
+      const href = (n as HTMLElement & { href?: string }).href;
+      return Boolean(href || n.getAttribute("href"));
+    });
+    if (!item) return;
+    (this.shadowRoot?.querySelector("sonic-pop") as Pop | null)?.hide();
+    this.dispatchEvent(
+      new CustomEvent("docs-search-close", { bubbles: true, composed: true }),
+    );
+  };
+  /** Text around the first match, matched characters highlighted. */
   getResultSearchString(result: any) {
-    const p = result.p;
-    const str = result.target
-      .split("")
-      .map((value, index) =>
-        p.includes(index)
-          ? "<span class='font-bold' style='color:var(--sc-info)'>" +
-            value +
-            "</span>"
-          : value,
-      )
-      .join("");
-    return str;
+    const p: number[] = Array.from(
+      fuzzysort.indexes?.(result) ?? result.indexes ?? result.p ?? [],
+    );
+    const target: string = result.target.replace(/\s/g, " ");
+    const first = p.length ? Math.min(...p) : 0;
+    const from = Math.max(0, first - SNIPPET_RADIUS);
+    const to = Math.min(target.length, first + SNIPPET_RADIUS * 2);
+    // The index already holds HTML entities: only escape raw tags.
+    const escape = (c: string) => (c === "<" ? "&lt;" : c === ">" ? "&gt;" : c);
+    let str = "";
+    for (let i = from; i < to; i++) {
+      const c = escape(target[i]);
+      str += p.includes(i) ? `<mark>${c}</mark>` : c;
+    }
+    return (from > 0 ? "…" : "") + str + (to < target.length ? "…" : "");
   }
   connectedCallback() {
     PublisherManager.get("docsSearch").search.onAssign((v) => this.search(v));
+    this.addEventListener("click", this.closeAfterNavigate, true);
     super.connectedCallback();
   }
 
+  disconnectedCallback() {
+    this.removeEventListener("click", this.closeAfterNavigate, true);
+    super.disconnectedCallback();
+  }
+
   firstUpdated() {
     if (this.setFocus) {
       setTimeout(() => {
@@ -125,81 +181,57 @@ export class DocsSearch extends LitElement {
         ${this.hidePopMenu
           ? nothing
           : html`
-              <sonic-menu
+              <div
                 slot="content"
-                class="max-w-[30rem] lg:max-w-[35rem] max-h-[50svh] overflow-auto  custom-scroll !left-0 !top-0 !relative"
+                class="w-[30rem] lg:w-[35rem] max-w-[calc(100vw-2rem)] max-h-[60svh] overflow-auto custom-scroll py-2"
               >
-                <sonic-list displayContents dataProvider="searchResult">
-                  <template>
-                    <div class="my-4">
-                      <div class="ml-3 mr-3 mb-1">
-                        <sonic-value
-                          key="title"
-                          class="font-bold text-lg "
-                        ></sonic-value>
-                      </div>
-                      <sonic-list subDataProvider="items">
-                        <template data-value="page">
-                          <sonic-menu-item
-                            formDataProvider="searchSelection"
-                            data-keyboard-nav="search-results doc-search"
-                            class="mt-1"
-                          >
-                            <sonic-icon
-                              slot="prefix"
-                              size="lg"
-                              library="heroicons"
-                              name="book-open"
-                            ></sonic-icon>
-                            <div>
-                              <sonic-value
-                                key="search"
-                                class="block font-medium "
-                              ></sonic-value>
-                            </div>
-                            <sonic-icon
-                              slot="suffix"
-                              size="lg"
-                              library="heroicons"
-                              name="chevron-right"
-                              class="opacity-40"
-                            ></sonic-icon>
-                          </sonic-menu-item>
-                        </template>
-                        <template>
-                          <sonic-menu-item
-                            formDataProvider="searchSelection"
-                            data-keyboard-nav="search-results doc-search"
-                            class="mt-1"
-                          >
-                            <div>
-                              <sonic-badge size="xs" ellipsis class="mb-1">
-                                <sonic-value
-                                  key="part"
-                                  class="block "
-                                ></sonic-value>
-                              </sonic-badge>
-                              <sonic-value
-                                key="search"
-                                class="block text-sm  font-normal pl-[.75rem]"
-                              ></sonic-value>
-                            </div>
-                            <sonic-icon
-                              slot="suffix"
-                              size="lg"
-                              library="heroicons"
-                              name="chevron-right"
-                              class="opacity-40"
-                            ></sonic-icon>
-                          </sonic-menu-item>
-                        </template>
-                      </sonic-list>
-                    </div>
-                  </template>
-                </sonic-list>
-              </sonic-menu>
+                ${this.results.length
+                  ? this.results.map((group) => this.renderGroup(group))
+                  : this.query.trim()
+                    ? html`<p class="px-3 py-2 text-sm text-neutral-500">
+                        No results
+                      </p>`
+                    : html`<p class="px-3 py-2 text-sm text-neutral-500">
+                        Type to search the documentation.
+                      </p>`}
+              </div>
             `}
       </sonic-pop>
     `;
   }
+
+  renderGroup(group: SearchGroup) {
+    return html`
+      <section class="py-1">
+        <sonic-menu-item
+          pushState
+          href=${group.href ?? nothing}
+          data-keyboard-nav="search-results doc-search"
+          size="sm"
+          class="w-full font-semibold"
+          ><span class="font-semibold">${group.title}</span></sonic-menu-item
+        >
+        ${group.items.map(
+          (item) => html`
+            <sonic-menu-item
+              pushState
+              href=${item.href}
+              data-keyboard-nav="search-results doc-search"
+              size="sm"
+              class="w-full"
+            >
+              <span class="block min-w-0 pl-3 text-left font-normal">
+                <span class="block truncate text-xs text-neutral-500"
+                  >${item.part}</span
+                >
+                <span class="snippet block text-sm line-clamp-2"
+                  >${unsafeHTML(item.search)}</span
+                >
+              </span>
+            </sonic-menu-item>
+          `,
+        )}
+      </section>
+    `;
+  }
 }

package/vite.config.mts

@@ -7,6 +7,7 @@ import { configDefaults } from "vitest/config";
 import path from "path";
 import fs from "fs";
 import { docsMockApiVitePlugin } from "./scripts/docs-mock-api-vite-plugin";
+import { docsMarkdownVitePlugin } from "./scripts/docs-markdown-vite-plugin";
 import { docsOpenInEditorPlugin } from "./scripts/docs-open-in-editor-plugin";
 
 function CustomHmr() {
@@ -90,7 +91,11 @@ export default defineConfig({
       },
     },
   },
-  base: "./",
+  // Docs SPA uses pathname routes (`/docs/...`); relative `./` breaks asset URLs on deep paths.
+  base:
+    libName === "docs" || process.env.npm_lifecycle_event === "dev"
+      ? "/"
+      : "./",
   test: {
     globals: true,
     environment: "jsdom",
@@ -129,7 +134,11 @@ export default defineConfig({
       include: ["src/**/*.css", "src/**/*.css?*"],
     }),
     ...(enableDocsMockApi
-      ? [docsMockApiVitePlugin(), docsOpenInEditorPlugin()]
+      ? [
+          docsMarkdownVitePlugin(),
+          docsMockApiVitePlugin(),
+          docsOpenInEditorPlugin(),
+        ]
       : []),
   ],
 });

package/.agents/skills/concorde-component-docs/SKILL.md

@@ -1,194 +0,0 @@
----
-name: concorde-component-docs
-description: >-
-  Writes and edits Concorde UI component documentation pages (*.md) in English
-  with consistent structure, tone, sonic-code examples, and API tables. Use when
-  creating or updating component docs under src/core/components/ui/, when
-  uniformizing documentation, or when the user references alert.md-style docs.
----
-
-# Concorde component documentation
-
-Apply this skill when **creating** or **editing** a component doc page (typically `src/core/components/ui/<component>/<component>.md`).
-
-Canonical examples: `alert.md`, `badge.md`, `link.md`, `image.md`.
-
-## Workflow
-
-### Creating a new page
-
-1. Read the component implementation (`.ts` / props, slots, reflected attributes, defaults).
-2. Draft the **intro** (what it does, when to use it, 1–2 critical APIs).
-3. Add **feature sections** in order of reader need (basic → variants → composition → edge cases → a11y).
-4. Add one **`<sonic-code>`** example per section; group enum variants in a single demo when practical.
-5. End with **`## API reference`** (attributes table, slots table if any).
-6. Run the [quality checklist](#quality-checklist).
-
-### Editing an existing page
-
-1. Preserve working examples; only change prose/structure to match this guide.
-2. Do not duplicate `## API reference` blocks—merge into one.
-3. Align intro tone and section titles with sibling docs; add missing API rows from source.
-4. Keep demo markup valid; avoid unrelated refactors in examples.
-
-## Page structure
-
-```markdown
-# ComponentName
-
-[Intro paragraph: 1–3 sentences. Purpose, primary use case, key props/slots.]
-
-## Basic example
-[or first topical section, e.g. ## Type, ## Href, ## Rounded]
-
-[Optional short prose before the example.]
-
-<sonic-code>
-  <template>
-    ...
-  </template>
-</sonic-code>
-
-## [Feature or variant name]
-
-...
-
-## API reference
-
-| Attribute | Values | Description |
-|----------|---------|-------------|
-| ... | ... | ... |
-
-| Slot | Description |
-|------|-------------|
-| ... | ... |
-```
-
-### Title (`#`)
-
-- Singular component name, Title Case: `# Alert`, `# Badge`, `# Link`, `# Image`.
-- Match the public tag name conceptually (`sonic-alert` → Alert).
-
-### Intro (required for new-style docs)
-
-One tight paragraph immediately after the title:
-
-- State **what** the component does and **when** to choose it.
-- Call out **defaults** and **constraints** only if they prevent misuse.
-- Formatting:
-  - **Bold** for emphasis on behavior (not for every noun).
-  - API names and tags in backticks; when listing several, **do not put commas between inline-code spans** (rendered as adjacent `<code>`). Join with **`/`**, **`and`**, or separate clauses—e.g. `` `label` `` / `` `text` ``, not `` `label` ``, `` `text` ``.
-  - Cross-link related components in prose: “aligned with **`sonic-button`**”, “pair with **`ratio="1/1"`**”.
-
-Avoid marketing fluff, long tutorials, and repeating the API table in the intro.
-
-### Section headings (`##` / `###`)
-
-- **Sentence case** or short Title Case; be consistent within one file.
-- Name sections after **one concern**: `Status`, `Size`, `Dismissible`, `Accessibility (\`announce\`)`, `Prefix and suffix slots`.
-- Use `###` for sub-variants of the same feature (e.g. `### AutoActive Strict vs partial`).
-- Put **`## API reference`** last—never in the middle.
-
-Suggested order (omit what does not apply):
-
-1. Basic example / primary API
-2. Visual variants (`type` / `status` / `variant` / `size` / …)
-3. Content model (slots, `label` / `text`, rich content)
-4. Composition patterns (inside buttons, with links, …)
-5. Behavioral flags (`dismissible` / `announce` / `cover` / …)
-6. Accessibility (dedicated section when non-obvious)
-7. API reference
-
-### Prose before examples
-
-- **Default first**: “With no `status`, behavior is `default`.” “Default **`loading`** is `lazy`.”
-- **Enums inline** when short: `` `outline` `` — border and text in the `type` color.
-- **Requirements**: stable `` `id` `` required for `dismissForever`; parent must constrain width for `ellipsis`.
-- **Implementation notes** only when they change usage: `localStorage`; `role="alert"`; remount to replay transitions.
-- Length: 0–4 sentences per section; longer only for accessibility or non-obvious behavior.
-
-## Live examples (`<sonic-code>`)
-
-Wrap all demos:
-
-```html
-<sonic-code>
-  <template>
-    <!-- demo markup -->
-  </template>
-</sonic-code>
-```
-
-Conventions:
-
-- Use Tailwind layout utilities already used in the design system docs: `grid gap-4` / `flex flex-wrap gap-2` / `items-center`.
-- Show **all enum values** in one row/grid when demonstrating `type`, `status`, or `size`.
-- Label variants in the UI (badge text, caption `<p class="mt-2">`) when comparison matters.
-- Prefer realistic copy over “Lorem ipsum” unless demonstrating truncation or length.
-- Interactive demos (buttons that mutate DOM) are allowed when they teach behavior—add one sentence explaining what to click.
-- Do not wrap API tables or long prose inside `<sonic-code>`.
-
-## API reference
-
-### Attributes table
-
-```markdown
-| Attribute | Values | Description |
-|----------|---------|-------------|
-| `name` | `a` · `b` (default `a`) | One line: behavior + default + interaction with other props |
-```
-
-- Column headers exactly: **Attribute**, **Values**, **Description**.
-- **Values**: list allowed literals separated by **middle dot (` · `)** or **`…`** for ranges (`2xs` … `2xl`)—**never commas between backtick spans**. Put **(default `…`)** in this column or in Description—be consistent within the file.
-- **Description**: imperative, factual; mention side effects (`removes from DOM`, `ignored when \`cover\` is set`).
-- Document boolean attributes as boolean in the table; no need to say “true/false” unless ambiguous.
-
-### Slots table
-
-```markdown
-| Slot | Description |
-|------|-------------|
-| *(default)* | Main label / message body |
-| `icon` | Replaces the default `sonic-icon` |
-```
-
-- If the component has **no slots**, state it in prose under the attributes table (see `image.md`).
-- Use *(default)* for the unnamed slot.
-
-### Single API block
-
-One `## API reference` section per file. If the source doc has duplicates, consolidate without losing rows.
-
-## Voice and language
-
-- **English only** for user-facing doc text.
-- Present tense, second person avoided; address the integrator (“Set **`announce`** when…”).
-- Prefer precise verbs: surface, navigate, truncate, persist, intercept.
-- Do not document internal CSS class names unless the doc already uses them for styling hooks (`[&[active]]:text-success` in examples is OK).
-
-## Quality checklist
-
-Before finishing, verify:
-
-- [ ] `#` title + intro paragraph present (for new or modernized pages).
-- [ ] Every `##` section (except API) has a `<sonic-code>` example unless it is pure sub-prose under a parent demo.
-- [ ] Defaults and required attributes are stated in prose or API table.
-- [ ] Accessibility called out where behavior affects AT (roles, `alt`, decorative icons).
-- [ ] Exactly one `## API reference`; attributes and slots match the component source.
-- [ ] No duplicate sections; heading levels skip only when using `###` under `##`.
-- [ ] Attribute/slot names match the implementation (camelCase in docs).
-- [ ] No comma-separated lists of inline-code terms in prose or API **Values** cells.
-
-## Anti-patterns
-
-- Long narrative guides, installation steps, or changelog in component `.md` files.
-- Examples without `<sonic-code>` wrappers.
-- API tables at the top of the page.
-- Mixing French and English in the same page.
-- Vague intros (“This component is very useful”) without API hints.
-- Separate micro-sections per enum value when one grid demo suffices.
-- Comma chains of inline code: `` `a` ``, `` `b` ``, and `` `c` `` (use `/`, ` · `, or `and` instead).
-
-## Reference template
-
-See [template.md](template.md) for a copy-paste skeleton.