@lapismd/design-core 0.1.0

package/src/shared/shell/app-shell/app-shell-persistence.ts

@@ -0,0 +1,70 @@
+import type { AppShellSide } from "./app-shell-controller.svelte.js";
+
+export const APP_SHELL_LAYOUT_VERSION = 1 as const;
+export const APP_SHELL_DEFAULT_STORAGE_KEY =
+  "@lapismd/design-core/app-shell-layout";
+
+export interface AppShellSidebarLayout {
+  side: AppShellSide;
+  collapsed: boolean;
+  closed: boolean;
+  width?: number;
+}
+
+export interface AppShellLayoutV1 {
+  version: typeof APP_SHELL_LAYOUT_VERSION;
+  panels: Record<string, AppShellSidebarLayout>;
+}
+
+export type AppShellLayoutChangeSource =
+  | "collapse"
+  | "close"
+  | "resize"
+  | "reset-width"
+  | "register"
+  | "unregister";
+
+export interface AppShellLayoutChangeEvent {
+  source: AppShellLayoutChangeSource;
+  panelId: string;
+}
+
+export interface AppShellLayoutPersistence {
+  load(): Promise<unknown | null>;
+  save(
+    layout: AppShellLayoutV1,
+    event: AppShellLayoutChangeEvent,
+  ): Promise<void>;
+}
+
+export interface AppShellPersistenceErrorEvent {
+  operation: "load" | "save";
+  error: unknown;
+}
+
+/**
+ * Browser storage adapter for the App Shell's versioned sidebar layout.
+ * Pass a Storage implementation in tests or non-window browser contexts.
+ */
+export function createLocalStorageAppShellLayoutPersistence(
+  key = APP_SHELL_DEFAULT_STORAGE_KEY,
+  storage?: Storage,
+): AppShellLayoutPersistence {
+  const resolveStorage = (): Storage => {
+    const resolved = storage ?? globalThis.localStorage;
+    if (!resolved) {
+      throw new Error("App Shell localStorage is not available.");
+    }
+    return resolved;
+  };
+
+  return {
+    async load() {
+      const value = resolveStorage().getItem(key);
+      return value ? (JSON.parse(value) as unknown) : null;
+    },
+    async save(layout) {
+      resolveStorage().setItem(key, JSON.stringify(layout));
+    },
+  };
+}

package/src/shared/shell/app-shell/app-shell-sidebar-context.svelte.ts

@@ -0,0 +1,34 @@
+import { getContext, setContext } from "svelte";
+import type {
+  AppShellSide,
+  AppShellSidebarController,
+} from "./app-shell-controller.svelte.js";
+
+const APP_SHELL_SIDEBAR_CONTEXT = Symbol("ui-minimal-app-shell-sidebar");
+export const APP_SHELL_SIDEBAR_LAYOUT_SYNC_EVENT =
+  "ui-shell-sidebar-layout-sync";
+
+export interface AppShellSidebarContext {
+  readonly side: AppShellSide;
+  readonly closeable: boolean;
+  readonly controller: AppShellSidebarController;
+  readonly dismissOverlay: () => void;
+}
+
+export function setAppShellSidebarContext(
+  context: AppShellSidebarContext,
+): AppShellSidebarContext {
+  return setContext(APP_SHELL_SIDEBAR_CONTEXT, context);
+}
+
+export function useAppShellSidebar(): AppShellSidebarContext {
+  const context = getContext<AppShellSidebarContext | undefined>(
+    APP_SHELL_SIDEBAR_CONTEXT,
+  );
+  if (!context) {
+    throw new Error(
+      "AppShell.Sidebar compound parts must be rendered inside AppShell.Sidebar",
+    );
+  }
+  return context;
+}

package/src/shared/shell/app-shell/app-shell-teleport.ts

@@ -0,0 +1,38 @@
+export interface AppShellTeleportOptions {
+  enabled: boolean;
+  target: HTMLElement | null;
+}
+
+/**
+ * Re-parent one compound part into a root-owned mobile lane while retaining
+ * its original desktop position.
+ */
+export function appShellTeleport(
+  node: HTMLElement,
+  options: AppShellTeleportOptions,
+): {
+  update: (next: AppShellTeleportOptions) => void;
+  destroy: () => void;
+} {
+  const anchor = document.createComment("app-shell-teleport");
+  node.before(anchor);
+
+  function restore(): void {
+    anchor.parentNode?.insertBefore(node, anchor.nextSibling);
+  }
+
+  function update(next: AppShellTeleportOptions): void {
+    if (next.enabled && next.target) next.target.appendChild(node);
+    else restore();
+  }
+
+  update(options);
+
+  return {
+    update,
+    destroy() {
+      restore();
+      anchor.remove();
+    },
+  };
+}

package/src/shared/shell/app-shell/examples/AppShellBodyDemo.svelte

@@ -0,0 +1,28 @@
+<div class="ui-shell-story-body-demo">
+  <header>
+    <p>Composable layout</p>
+    <h2>Application overview</h2>
+    <span>
+      The center content remains application-owned while the shell provides
+      bounded geometry.
+    </span>
+  </header>
+
+  <div class="ui-shell-story-card-grid">
+    <section>
+      <span>Active CVs</span>
+      <strong>12</strong>
+      <p>Three updated this week</p>
+    </section>
+    <section>
+      <span>Applications</span>
+      <strong>28</strong>
+      <p>Five need follow-up</p>
+    </section>
+    <section>
+      <span>Interview notes</span>
+      <strong>7</strong>
+      <p>All stored locally</p>
+    </section>
+  </div>
+</div>

package/src/shared/shell/app-shell/examples/AppShellCompleteDemo.svelte

@@ -0,0 +1,123 @@
+<script lang="ts">
+  import { untrack } from "svelte";
+  import type {
+    AppShellController,
+    AppShellDisplayMode,
+    AppShellSide,
+    AppShellSidebarController,
+  } from "../app-shell-controller.svelte.js";
+  import { AppShell } from "../index.js";
+  import AppShellConversationDemo from "./AppShellConversationDemo.svelte";
+  import AppShellMarkdownDocumentDemo from "./AppShellMarkdownDocumentDemo.svelte";
+  import AppShellMarkdownFilesDemo from "./AppShellMarkdownFilesDemo.svelte";
+  import AppShellProjectSidebarDemo from "./AppShellProjectSidebarDemo.svelte";
+  import AppShellToolbarDemo from "./AppShellToolbarDemo.svelte";
+
+  let {
+    controller,
+    projectSidebar,
+    displayMode = "auto",
+    mobileBreakpoint = 1024,
+    desktopMinMainWidth,
+    frameClass,
+    showBodySidebar = true,
+  }: {
+    controller: AppShellController;
+    projectSidebar: AppShellSidebarController;
+    displayMode?: AppShellDisplayMode;
+    mobileBreakpoint?: number;
+    desktopMinMainWidth?: number;
+    frameClass?: string;
+    /** Whether the document TOC body sidebar starts open on the right. */
+    showBodySidebar?: boolean;
+  } = $props();
+
+  let selectedProject = $state("lapis-notes");
+  let selectedMarkdownFile = $state("README.md");
+  let bodySidebarSide = $state<AppShellSide | undefined>(
+    untrack(() => (showBodySidebar ? "right" : undefined)),
+  );
+
+  function selectProject(projectId: string): void {
+    selectedProject = projectId;
+    if (projectId) {
+      controller.left.expand();
+      if (!selectedMarkdownFile) selectedMarkdownFile = "README.md";
+    } else {
+      controller.left.close();
+    }
+  }
+
+  function openMarkdownFile(file: string): void {
+    selectedMarkdownFile = file;
+    if (!bodySidebarSide) bodySidebarSide = "right";
+  }
+
+  function toggleBodySidebar(side: AppShellSide): void {
+    if (!selectedMarkdownFile) selectedMarkdownFile = "README.md";
+    bodySidebarSide = bodySidebarSide === side ? undefined : side;
+  }
+</script>
+
+<div class={["ui-shell-story-frame", frameClass].filter(Boolean).join(" ")}>
+  <AppShell.Root
+    {controller}
+    {displayMode}
+    {mobileBreakpoint}
+    {desktopMinMainWidth}
+    class="ui-shell-story-surface ui-shell-story-complete"
+  >
+    <AppShell.Sidebar
+      side="left"
+      sidebarController={projectSidebar}
+      label="Projects sidebar"
+      mobileLabel="Projects"
+      resizeLabel="Resize projects sidebar"
+      variant="outer"
+      closeable
+      revealOnEdgeHover
+      edgeRevealLabel="Preview projects sidebar"
+    >
+      <AppShellProjectSidebarDemo
+        sidebar={projectSidebar}
+        {selectedProject}
+        onSelectProject={selectProject}
+      />
+    </AppShell.Sidebar>
+
+    <AppShell.Sidebar
+      side="left"
+      label="Files sidebar"
+      mobileLabel="Files"
+      resizeLabel="Resize files sidebar"
+    >
+      <AppShellMarkdownFilesDemo
+        {controller}
+        {projectSidebar}
+        selectedFile={selectedMarkdownFile}
+        onSelectFile={openMarkdownFile}
+      />
+    </AppShell.Sidebar>
+
+    <AppShell.Main>
+      <AppShell.Toolbar>
+        <AppShellToolbarDemo leftSidebarName="files" />
+      </AppShell.Toolbar>
+      <AppShellMarkdownDocumentDemo
+        file={selectedMarkdownFile}
+        sidebarSide={bodySidebarSide}
+        onToggleSidebar={toggleBodySidebar}
+      />
+    </AppShell.Main>
+
+    <AppShell.Sidebar
+      side="right"
+      label="AI sidebar"
+      mobileLabel="AI conversation"
+      resizeLabel="Resize AI sidebar"
+      closeable
+    >
+      <AppShellConversationDemo {controller} />
+    </AppShell.Sidebar>
+  </AppShell.Root>
+</div>

package/src/shared/shell/app-shell/examples/AppShellConversationDemo.svelte

@@ -0,0 +1,143 @@
+<script lang="ts">
+  import SparklesIcon from "@lucide/svelte/icons/sparkles";
+  import {
+    Composer,
+    Layout,
+    Message,
+    MessageBubble,
+    MessageList,
+    MessageMetadata,
+    SystemMessage,
+    ToolCalls,
+  } from "../../../ai/chat.js";
+  import ReactionBar from "../../../ai/experimental/reaction-bar/ReactionBar.svelte";
+  import Reasoning from "../../../ai/experimental/reasoning/Reasoning.svelte";
+  import TypingIndicator from "../../../ai/experimental/typing-indicator/TypingIndicator.svelte";
+  import UnreadDivider from "../../../ai/experimental/unread-divider/UnreadDivider.svelte";
+  import { Button } from "../../../shadcn/button/index.js";
+  import { AppShell } from "../index.js";
+  import type { AppShellController } from "../app-shell-controller.svelte.js";
+
+  let {
+    controller,
+  }: {
+    controller: AppShellController;
+  } = $props();
+
+  let draft = $state("");
+  let submitted = $state("");
+</script>
+
+{#snippet inspectDetail()}
+  Checked the shared AI source and public package boundaries.
+{/snippet}
+
+<AppShell.Sidebar.Header class="ui-shell-story-ai-header">
+  {#if controller.mobile.resolvedMode === "mobile" || !controller.right.collapsed}
+    <SparklesIcon aria-hidden="true" />
+    <strong>AI conversation</strong>
+  {/if}
+  <AppShell.Sidebar.Close />
+</AppShell.Sidebar.Header>
+
+<AppShell.Sidebar.Body class="ui-shell-story-ai-body">
+  {#if controller.mobile.resolvedMode === "desktop" && controller.right.collapsed}
+    <Button
+      variant="ghost"
+      size="icon-sm"
+      aria-label="Open AI conversation"
+      title="Open AI conversation"
+      onclick={() => controller.right.expand()}
+    >
+      <SparklesIcon aria-hidden="true" />
+    </Button>
+  {:else}
+    <Layout density="compact" aria-label="Complete AI conversation">
+      {#snippet composer()}
+        <div class="ui-shell-story-ai-composer">
+          <TypingIndicator names={["Ada"]} />
+          <Composer
+            density="compact"
+            bind:value={draft}
+            onSubmit={(value) => {
+              submitted = value;
+            }}
+          />
+        </div>
+      {/snippet}
+
+      <MessageList
+        density="compact"
+        latestMessageId={submitted || "assistant-2"}
+      >
+        <SystemMessage variant="divider">Today</SystemMessage>
+        <Message sender="assistant">
+          {#snippet name()}Assistant{/snippet}
+          <MessageBubble>
+            I can inspect the release and propose a concise summary.
+          </MessageBubble>
+          {#snippet metadata()}
+            <MessageMetadata timestamp="10:41" />
+          {/snippet}
+        </Message>
+        <Message sender="user">
+          <MessageBubble>Review the changed files first.</MessageBubble>
+        </Message>
+        <UnreadDivider />
+        <Message sender="assistant">
+          <MessageBubble variant="ghost">
+            <Reasoning
+              duration="3s"
+              preview="I should inspect the package boundaries."
+            >
+              {#snippet children()}
+                I checked the UI package boundaries and kept networking in the
+                host application.
+              {/snippet}
+            </Reasoning>
+            <ToolCalls
+              calls={[
+                {
+                  id: "inspect",
+                  name: "Inspect package",
+                  target: "src/shared/ai",
+                  status: "complete",
+                  duration: "420ms",
+                  detail: inspectDetail,
+                },
+              ]}
+            />
+            The release adds reusable Svelte 5 Chat primitives while preserving the
+            existing AI panel API.
+          </MessageBubble>
+          <ReactionBar
+            reactions={[
+              { emoji: "🎉", count: 3, selected: true },
+              { emoji: "👀", count: 1 },
+            ]}
+          />
+        </Message>
+        <Message sender="user">
+          <MessageBubble>
+            Keep the shared shell independent from routing and persistence.
+          </MessageBubble>
+        </Message>
+        <Message sender="assistant">
+          <MessageBubble variant="ghost">
+            The shell now owns only geometry and sidebar state. Project
+            selection, file navigation, and message submission remain with the
+            host application.
+          </MessageBubble>
+        </Message>
+        {#if submitted}
+          <Message sender="user">
+            <MessageBubble>{submitted}</MessageBubble>
+            {#snippet metadata()}
+              <MessageMetadata timestamp="Now" status="sent" />
+            {/snippet}
+          </Message>
+        {/if}
+      </MessageList>
+    </Layout>
+  {/if}
+</AppShell.Sidebar.Body>

package/src/shared/shell/app-shell/examples/AppShellFilesSidebarDemo.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+  import FileCode2Icon from "@lucide/svelte/icons/file-code-2";
+  import FileTextIcon from "@lucide/svelte/icons/file-text";
+  import FolderIcon from "@lucide/svelte/icons/folder";
+  import FolderOpenIcon from "@lucide/svelte/icons/folder-open";
+  import type {
+    AppShellController,
+    AppShellSidebarController,
+  } from "../app-shell-controller.svelte.js";
+  import { AppShell } from "../index.js";
+
+  let {
+    controller,
+    projectSidebar,
+    selectedProject,
+  }: {
+    controller: AppShellController;
+    projectSidebar: AppShellSidebarController;
+    selectedProject: string;
+  } = $props();
+
+  let sidebar = $derived(controller.left);
+  let projectName = $derived(
+    selectedProject === "lapis-notes"
+      ? "Lapis Notes"
+      : selectedProject === "ui-catalog"
+        ? "UI Catalog"
+        : "CV Studio",
+  );
+</script>
+
+<AppShell.Sidebar.Header class="ui-shell-story-files-header">
+  <AppShell.Sidebar.Toggle
+    side="left"
+    sidebarController={projectSidebar}
+    sidebarName="projects"
+    previewOnHover
+  />
+  <FolderOpenIcon aria-hidden="true" />
+  {#if !sidebar.collapsed}
+    <strong>Files</strong>
+  {/if}
+</AppShell.Sidebar.Header>
+
+<AppShell.Sidebar.Body class="ui-shell-story-files-body">
+  <nav aria-label={`${projectName} files`}>
+    <button type="button" aria-label="Source folder">
+      <FolderIcon aria-hidden="true" />
+      {#if !sidebar.collapsed}<span>src</span>{/if}
+    </button>
+    <button type="button" aria-label="Shared folder">
+      <FolderIcon aria-hidden="true" />
+      {#if !sidebar.collapsed}<span>shared</span>{/if}
+    </button>
+    <button type="button" aria-label="App shell file">
+      <FileCode2Icon aria-hidden="true" />
+      {#if !sidebar.collapsed}<span>AppShell.svelte</span>{/if}
+    </button>
+    <button type="button" aria-label="Project readme">
+      <FileTextIcon aria-hidden="true" />
+      {#if !sidebar.collapsed}<span>README.md</span>{/if}
+    </button>
+  </nav>
+</AppShell.Sidebar.Body>
+
+<AppShell.Sidebar.Footer class="ui-shell-story-files-footer">
+  {#if !sidebar.collapsed}
+    <span>{projectName}</span>
+  {/if}
+</AppShell.Sidebar.Footer>

package/src/shared/shell/app-shell/examples/AppShellMarkdownDocumentDemo.svelte

@@ -0,0 +1,112 @@
+<script lang="ts">
+  import FileTextIcon from "@lucide/svelte/icons/file-text";
+  import type { AppShellSide } from "../app-shell-controller.svelte.js";
+  import { AppShell } from "../index.js";
+
+  let {
+    file,
+    sidebarSide,
+    onToggleSidebar,
+  }: {
+    file: string;
+    sidebarSide?: AppShellSide;
+    onToggleSidebar: (side: AppShellSide) => void;
+  } = $props();
+
+  const sections = [
+    "Overview",
+    "Installation",
+    "Project structure",
+    "Shell composition",
+    "Body regions",
+    "Table of contents",
+    "Scrolling",
+    "Accessibility",
+    "Styling tokens",
+    "Consumer state",
+    "Testing",
+    "Deployment",
+  ];
+</script>
+
+{#snippet tableOfContents()}
+  <nav class="ui-shell-story-document-toc" aria-label="Document sections">
+    <span>On this page</span>
+    {#each sections as section, index}
+      <a
+        href={`#shell-document-section-${index}`}
+        aria-current={index === 0 ? "location" : undefined}
+      >
+        {section}
+      </a>
+    {/each}
+  </nav>
+{/snippet}
+
+<AppShell.Body layout="regions" label="Markdown document">
+  <AppShell.Body.Toggle
+    side="left"
+    target="document-table-of-contents"
+    pressed={sidebarSide === "left"}
+    label={sidebarSide === "left"
+      ? "Hide table of contents on left"
+      : "Show table of contents on left"}
+    onclick={() => onToggleSidebar("left")}
+  />
+  <AppShell.Body.Toggle
+    side="right"
+    target="document-table-of-contents"
+    pressed={sidebarSide === "right"}
+    label={sidebarSide === "right"
+      ? "Hide table of contents on right"
+      : "Show table of contents on right"}
+    onclick={() => onToggleSidebar("right")}
+  />
+
+  <AppShell.Body.Sidebar
+    panelId="document-table-of-contents"
+    side={sidebarSide ?? "right"}
+    open={sidebarSide !== undefined}
+    label="Table of contents"
+    mobileLabel="Document contents"
+  >
+    {@render tableOfContents()}
+  </AppShell.Body.Sidebar>
+
+  <AppShell.Body.Content label={file ? `${file} content` : "Document content"}>
+    {#if file}
+      <article class="ui-shell-story-document">
+        <header>
+          <span>Markdown document</span>
+          <h2>{file}</h2>
+          <p>
+            Body sidebars are local to the document surface, so outer project
+            and file navigation keep their own independent geometry.
+          </p>
+        </header>
+
+        {#each sections as section, index}
+          <section id={`shell-document-section-${index}`}>
+            <h3>{section}</h3>
+            <p>
+              This section demonstrates independently scrolling document
+              content. The shell owns the bounded regions while the application
+              decides when the table of contents is present and which side it
+              occupies.
+            </p>
+            <p>
+              Markdown rendering, selection, routing, and document state remain
+              consumer-owned.
+            </p>
+          </section>
+        {/each}
+      </article>
+    {:else}
+      <div class="ui-shell-story-document-empty">
+        <FileTextIcon aria-hidden="true" />
+        <strong>Select a Markdown file</strong>
+        <span>Its table of contents can open on either side of the body.</span>
+      </div>
+    {/if}
+  </AppShell.Body.Content>
+</AppShell.Body>

package/src/shared/shell/app-shell/examples/AppShellMarkdownFilesDemo.svelte

@@ -0,0 +1,67 @@
+<script lang="ts">
+  import FileTextIcon from "@lucide/svelte/icons/file-text";
+  import FolderOpenIcon from "@lucide/svelte/icons/folder-open";
+  import type {
+    AppShellController,
+    AppShellSidebarController,
+  } from "../app-shell-controller.svelte.js";
+  import { AppShell } from "../index.js";
+
+  let {
+    controller,
+    projectSidebar,
+    selectedFile,
+    onSelectFile,
+  }: {
+    controller: AppShellController;
+    projectSidebar?: AppShellSidebarController;
+    selectedFile: string;
+    onSelectFile: (file: string) => void;
+  } = $props();
+
+  const files = ["README.md", "architecture.md", "contributing.md"];
+  let sidebar = $derived(controller.left);
+  let compact = $derived(
+    controller.mobile.resolvedMode === "desktop" && sidebar.collapsed,
+  );
+</script>
+
+<AppShell.Sidebar.Header class="ui-shell-story-files-header">
+  {#if projectSidebar}
+    <AppShell.Sidebar.Toggle
+      side="left"
+      sidebarController={projectSidebar}
+      sidebarName="projects"
+      previewOnHover
+    />
+  {:else}
+    <AppShell.Sidebar.Toggle side="left" />
+  {/if}
+  <FolderOpenIcon aria-hidden="true" />
+  {#if !compact}
+    <strong>Markdown files</strong>
+  {/if}
+</AppShell.Sidebar.Header>
+
+<AppShell.Sidebar.Body class="ui-shell-story-files-body">
+  <nav aria-label="Documentation files">
+    {#each files as file}
+      <button
+        type="button"
+        aria-label={`Open ${file}`}
+        aria-pressed={selectedFile === file}
+        data-active={selectedFile === file ? "" : undefined}
+        onclick={() => onSelectFile(file)}
+      >
+        <FileTextIcon aria-hidden="true" />
+        {#if !compact}<span>{file}</span>{/if}
+      </button>
+    {/each}
+  </nav>
+</AppShell.Sidebar.Body>
+
+<AppShell.Sidebar.Footer class="ui-shell-story-files-footer">
+  {#if !compact}
+    <span>Documentation</span>
+  {/if}
+</AppShell.Sidebar.Footer>