@typed-grid-areas/svelte 0.0.0 → 0.1.0

package/dist/Grid.svelte

@@ -0,0 +1,67 @@
+<!--
+  @component
+  A grid instance: its size container (when the definition has breakpoints),
+  the grid element (a `div`, or the element your `child` snippet renders),
+  and the definition's CSS in `<svelte:head>`. Rendered through the component
+  `createGridComponent` returns, which supplies `definition` and `outerArea`.
+-->
+<script lang="ts">
+  import { BROWSER, DEV } from "esm-env";
+  import { onDestroy, untrack } from "svelte";
+  import { createAttachmentKey } from "svelte/attachments";
+  import type { GridConfig } from "typed-grid-areas";
+  import { gridMarkup, gridStyleTags } from "typed-grid-areas/adapter";
+  import { slotCheckAttachment } from "./slotCheck.js";
+  import { claimServerStyle, joinStyleOwners } from "./styleOwners.js";
+  import type { GridRootProps } from "./types.js";
+
+  type Props = GridRootProps & {
+    definition: GridConfig<string>;
+    outerArea?: string;
+  };
+
+  let { definition, outerArea, child, children, ...rest }: Props = $props();
+
+  // `createGridComponent` fixes the definition for good.
+  const config = untrack(() => definition);
+  const markup = gridMarkup(config);
+  const styleTag = gridStyleTags([config]);
+
+  // Whether this instance renders the definition's CSS: one per definition does.
+  let ownsStyle = $state(false);
+  if (BROWSER) {
+    const membership = joinStyleOwners(markup.id, () => (ownsStyle = true));
+    ownsStyle = membership.owns;
+    onDestroy(membership.leave);
+  } else {
+    ownsStyle = claimServerStyle(markup.id);
+  }
+
+  // In development, the grid element (yours too, through `child`) checks its slots.
+  const checkSlots = DEV ? { [createAttachmentKey()]: slotCheckAttachment(config) } : {};
+
+  const elements = $derived(markup.elements(outerArea));
+  const gridProps = $derived({ ...rest, ...elements.grid.attributes, ...checkSlots });
+</script>
+
+<svelte:head>
+  {#if ownsStyle}
+    {@html styleTag}
+  {/if}
+</svelte:head>
+
+{#snippet grid()}
+  {#if child}
+    {@render child({ props: gridProps })}
+  {:else}
+    <div {...gridProps}>{@render children?.()}</div>
+  {/if}
+{/snippet}
+
+{#if elements.sizeContainer}
+  <div {...elements.sizeContainer.attributes} style={elements.sizeContainer.styleText}>
+    {@render grid()}
+  </div>
+{:else}
+  {@render grid()}
+{/if}

package/dist/Grid.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { GridConfig } from "typed-grid-areas";
+import type { GridRootProps } from "./types.ts";
+type Props = GridRootProps & {
+    definition: GridConfig<string>;
+    outerArea?: string;
+};
+/**
+ * A grid instance: its size container (when the definition has breakpoints),
+ * the grid element (a `div`, or the element your `child` snippet renders),
+ * and the definition's CSS in `<svelte:head>`. Rendered through the component
+ * `createGridComponent` returns, which supplies `definition` and `outerArea`.
+ */
+declare const Grid: import("svelte").Component<Props, {}, "">;
+type Grid = ReturnType<typeof Grid>;
+export default Grid;

package/dist/Slot.svelte

@@ -0,0 +1,21 @@
+<!--
+  @component
+  The slot filling one area: a `div`, or the element your `child` snippet
+  renders, marked with the area's `data-area`. Rendered through the
+  component `createGridComponent` returns, which supplies `area`.
+-->
+<script lang="ts">
+  import type { SlotProps } from "./types.js";
+
+  type Props = SlotProps & { area: string };
+
+  let { area, child, children, ...rest }: Props = $props();
+
+  const slotProps = $derived({ ...rest, "data-area": area });
+</script>
+
+{#if child}
+  {@render child({ props: slotProps })}
+{:else}
+  <div {...slotProps}>{@render children?.()}</div>
+{/if}

package/dist/Slot.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { SlotProps } from "./types.ts";
+type Props = SlotProps & {
+    area: string;
+};
+/**
+ * The slot filling one area: a `div`, or the element your `child` snippet
+ * renders, marked with the area's `data-area`. Rendered through the
+ * component `createGridComponent` returns, which supplies `area`.
+ */
+declare const Slot: import("svelte").Component<Props, {}, "">;
+type Slot = ReturnType<typeof Slot>;
+export default Slot;

package/dist/createGridComponent.d.ts

@@ -0,0 +1,28 @@
+import type { GridConfig } from "typed-grid-areas";
+import type { GridComponent, GridComponentOptions } from "./types.ts";
+/**
+ * Turns a definition into the component it renders as.
+ *
+ * `<Card>` renders the grid (inside its own size container when the
+ * definition has breakpoints) and puts the definition's CSS in `<head>`;
+ * `<Card.icon>` renders the slot that fills the `icon` area. Both take any
+ * attribute a `div` takes, children, and a `child` snippet to render your
+ * own element instead of the `div`.
+ *
+ * Create grid components once per definition, in a module (`.ts`, or a
+ * component's `<script module>`).
+ *
+ * @example
+ * ```ts
+ * const Content = createGridComponent(
+ *   defineLayout({ areas: ["icon?", "title"], layouts: [{ template: "icon title" }] }),
+ * );
+ * export const Card = createGridComponent(
+ *   defineLayout({ areas: ["input?", "content"], layouts: [{ template: "input content" }] }),
+ *   { nest: { content: Content } },
+ * );
+ * ```
+ */
+export declare function createGridComponent<TAreaName extends string, const TNest extends GridComponentOptions<TAreaName>["nest"] = {}>(definition: GridConfig<TAreaName>, options?: {
+    nest?: TNest;
+}): GridComponent<TAreaName, TNest>;

package/dist/createGridComponent.js

@@ -0,0 +1,71 @@
+import Grid from "./Grid.svelte";
+import Slot from "./Slot.svelte";
+/**
+ * `component` with some props fixed: Svelte 5's public component signature,
+ * `(internals, props)`, forwarding `internals` untouched and `props` through
+ * a proxy that answers the fixed props itself and reads every other prop
+ * from the caller's props live, so they stay reactive.
+ */
+function withFixedProps(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+component, fixed) {
+    const isFixed = (key) => typeof key === "string" && Object.hasOwn(fixed, key);
+    return (internals, props) => component(internals, new Proxy(props, {
+        get: (target, key, receiver) => isFixed(key) ? fixed[key] : Reflect.get(target, key, receiver),
+        has: (target, key) => isFixed(key) || Reflect.has(target, key),
+        ownKeys: target => [
+            ...Reflect.ownKeys(target).filter(key => !isFixed(key)),
+            ...Object.keys(fixed),
+        ],
+        getOwnPropertyDescriptor: (target, key) => isFixed(key)
+            ? { value: fixed[key], enumerable: true, configurable: true, writable: false }
+            : Reflect.getOwnPropertyDescriptor(target, key),
+    }));
+}
+/** The members (one per area) a grid component carries, for nesting it. */
+const MEMBERS = Symbol("typed-grid-areas members");
+/**
+ * Defines `members` on a component. `defineProperty`, because an area may be
+ * named like a function's own read-only properties (`name`, `length`).
+ */
+function withMembers(component, members) {
+    for (const [key, value] of Object.entries(members)) {
+        Object.defineProperty(component, key, { value, enumerable: true, configurable: true });
+    }
+    Object.defineProperty(component, MEMBERS, { value: members });
+    return component;
+}
+/**
+ * Turns a definition into the component it renders as.
+ *
+ * `<Card>` renders the grid (inside its own size container when the
+ * definition has breakpoints) and puts the definition's CSS in `<head>`;
+ * `<Card.icon>` renders the slot that fills the `icon` area. Both take any
+ * attribute a `div` takes, children, and a `child` snippet to render your
+ * own element instead of the `div`.
+ *
+ * Create grid components once per definition, in a module (`.ts`, or a
+ * component's `<script module>`).
+ *
+ * @example
+ * ```ts
+ * const Content = createGridComponent(
+ *   defineLayout({ areas: ["icon?", "title"], layouts: [{ template: "icon title" }] }),
+ * );
+ * export const Card = createGridComponent(
+ *   defineLayout({ areas: ["input?", "content"], layouts: [{ template: "input content" }] }),
+ *   { nest: { content: Content } },
+ * );
+ * ```
+ */
+export function createGridComponent(definition, options = {}) {
+    const members = {};
+    for (const area of definition.areas) {
+        const nested = options.nest?.[area];
+        members[area] =
+            nested === undefined
+                ? withFixedProps(Slot, { area })
+                : withMembers(withFixedProps(nested, { outerArea: area }), nested[MEMBERS] ?? {});
+    }
+    return withMembers(withFixedProps(Grid, { definition }), members);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createGridComponent } from "./createGridComponent.ts";
+export type { ChildSnippetProps, GridComponent, GridComponentOptions, GridRootProps, SlotComponent, SlotProps, } from "./types.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export { createGridComponent } from "./createGridComponent.js";

package/dist/slotCheck.d.ts

@@ -0,0 +1,9 @@
+import type { Attachment } from "svelte/attachments";
+import type { GridConfig } from "typed-grid-areas";
+/**
+ * The development slot check, as an attachment for the grid element: it
+ * checks the grid's slots once mounted, then again whenever its direct
+ * children or their `data-area` change (runes mode has no after-update
+ * hook), logging each distinct set of problems once.
+ */
+export declare function slotCheckAttachment(definition: GridConfig<string>): Attachment<Element>;

package/dist/slotCheck.js

@@ -0,0 +1,33 @@
+import { createSlotCheck } from "typed-grid-areas/adapter";
+/**
+ * The development slot check, as an attachment for the grid element: it
+ * checks the grid's slots once mounted, then again whenever its direct
+ * children or their `data-area` change (runes mode has no after-update
+ * hook), logging each distinct set of problems once.
+ */
+export function slotCheckAttachment(definition) {
+    return grid => {
+        const check = createSlotCheck(definition, {
+            strayChildRemedy: "make it a slot with a `child` snippet",
+        });
+        const run = () => {
+            for (const warning of check(grid)) {
+                // eslint-disable-next-line no-console
+                console.warn(warning);
+            }
+        };
+        run();
+        const observer = new MutationObserver(records => {
+            if (records.some(record => record.target === grid || record.target.parentNode === grid)) {
+                run();
+            }
+        });
+        observer.observe(grid, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ["data-area"],
+        });
+        return () => observer.disconnect();
+    };
+}

package/dist/styleOwners.d.ts

@@ -0,0 +1,14 @@
+/**
+ * On the server, during a component's render: whether this instance is the
+ * first of its definition in the current `render()`, and so renders its CSS.
+ */
+export declare function claimServerStyle(id: string): boolean;
+/**
+ * In the browser, while a component initialises: joins the definition's
+ * instances. The first owns the style tag; when it leaves, the next one
+ * takes over (`takeOver` is called), and the tag goes away with the last.
+ */
+export declare function joinStyleOwners(id: string, takeOver: () => void): {
+    owns: boolean;
+    leave: () => void;
+};

package/dist/styleOwners.js

@@ -0,0 +1,51 @@
+/**
+ * Which instance of a definition renders its CSS (ADR 0005). Svelte's
+ * `<svelte:head>` doesn't deduplicate, so exactly one instance per
+ * definition renders the style tag there: the first to render.
+ */
+import { getAbortSignal } from "svelte";
+/** Per server render (one abort signal each), the grid ids whose CSS is already rendered. */
+const rendered = new WeakMap();
+/**
+ * On the server, during a component's render: whether this instance is the
+ * first of its definition in the current `render()`, and so renders its CSS.
+ */
+export function claimServerStyle(id) {
+    const signal = getAbortSignal();
+    let ids = rendered.get(signal);
+    if (ids === undefined) {
+        ids = new Set();
+        rendered.set(signal, ids);
+    }
+    if (ids.has(id)) {
+        return false;
+    }
+    ids.add(id);
+    return true;
+}
+/** In the browser, the mounted instances of each definition, oldest first. */
+const owners = new Map();
+/**
+ * In the browser, while a component initialises: joins the definition's
+ * instances. The first owns the style tag; when it leaves, the next one
+ * takes over (`takeOver` is called), and the tag goes away with the last.
+ */
+export function joinStyleOwners(id, takeOver) {
+    const instances = owners.get(id) ?? [];
+    owners.set(id, instances);
+    const owner = { takeOver };
+    instances.push(owner);
+    return {
+        owns: instances[0] === owner,
+        leave() {
+            const index = instances.indexOf(owner);
+            instances.splice(index, 1);
+            if (index === 0) {
+                instances[0]?.takeOver();
+            }
+            if (instances.length === 0) {
+                owners.delete(id);
+            }
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import type { Component, Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * What a `child` snippet receives: the attributes to spread onto your own
+ * element, `{#snippet child({ props })}<label {...props}>…</label>{/snippet}`.
+ */
+export type ChildSnippetProps = {
+    props: Record<string, unknown>;
+};
+/**
+ * Props of a slot component (`<Card.icon>`): anything a `div` takes, plus a
+ * `child` snippet to render your own element instead of the `div`.
+ */
+export type SlotProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /**
+     * Renders your own element as the slot (or grid) instead of a `div`:
+     * spread `props` onto it. Bits UI's convention.
+     */
+    child?: Snippet<[ChildSnippetProps]>;
+    children?: Snippet;
+};
+/** Props of a grid's component (`<Card>`): the same as a slot's. */
+export type GridRootProps = SlotProps;
+/** A slot component (`<Card.icon>`): renders the element that fills one area. */
+export type SlotComponent = Component<SlotProps>;
+/**
+ * The component a definition renders as: the grid itself, with a slot
+ * component per area, named exactly like the area. An area nested through
+ * `nest` is the nested grid's component instead, with that grid's slots as
+ * its members (`<Card.content.icon>`).
+ */
+export type GridComponent<TAreaName extends string, TNest = {}> = Component<GridRootProps> & {
+    readonly [K in TAreaName]: K extends keyof TNest ? TNest[K] : SlotComponent;
+};
+/** Any grid component, whatever its areas. */
+export type AnyGridComponent = GridComponent<any, any>;
+/** Options of `createGridComponent`. */
+export type GridComponentOptions<TAreaName extends string> = {
+    /**
+     * Grids nested into areas of this one: `nest: { content: Content }` makes
+     * `<Card.content>` both the `content` slot and the grid `Content`.
+     */
+    nest?: {
+        readonly [K in TAreaName]?: AnyGridComponent;
+    };
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1 +1,59 @@
-{"name":"@typed-grid-areas/svelte","version":"0.0.0"}
+{
+  "name": "@typed-grid-areas/svelte",
+  "version": "0.1.0",
+  "description": "Svelte adapter for typed-grid-areas: render a grid definition as typed slot components.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MichaelBuss/typed-grid-areas.git",
+    "directory": "packages/svelte"
+  },
+  "homepage": "https://github.com/MichaelBuss/typed-grid-areas#readme",
+  "bugs": {
+    "url": "https://github.com/MichaelBuss/typed-grid-areas/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "buildSources": {
+    "dist": [
+      "src/lib"
+    ]
+  },
+  "scripts": {
+    "build": "svelte-package -i src/lib -o dist",
+    "prepack": "npm run build 1>&2 && cp ../../README.md ../../LICENSE .",
+    "postpack": "rm README.md LICENSE",
+    "test": "vitest run --project unit --project node",
+    "test:browser": "vitest run --project browser --project browser-development",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json --fail-on-warnings"
+  },
+  "peerDependencies": {
+    "svelte": "^5.57.0"
+  },
+  "dependencies": {
+    "esm-env": "^1.2.2",
+    "typed-grid-areas": "^0.2.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^3.0.1",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@typed-grid-areas/acceptance": "*",
+    "@types/node": "^22.10.5",
+    "@vitest/browser-playwright": "^5.0.1",
+    "playwright": "^1.64.1",
+    "svelte": "^5.57.3",
+    "svelte-check": "^4.7.7",
+    "typescript": "~6.0.3",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.1",
+    "vitest-browser-svelte": "^3.1.0"
+  }
+}