@typed-grid-areas/vue 0.0.0 → 0.1.0

package/dist/asChild.d.ts

@@ -0,0 +1,8 @@
+import { type Ref, type VNode } from "vue";
+/**
+ * Renders your own element in place of the adapter's `div`, Reka UI's `Slot`
+ * algorithm: the first child that isn't a comment, cloned with `attrs` merged
+ * into its props (its own props win, classes and styles combine, handlers
+ * chain) and `forced` on top, its own ref kept and `ref` (when given) added.
+ */
+export declare function renderAsChild(children: ReadonlyArray<VNode> | undefined, attrs: Record<string, unknown>, forced: Record<string, unknown>, ref?: Ref<Element | null>): Array<VNode> | VNode | null;

package/dist/asChild.js

@@ -0,0 +1,36 @@
+import { cloneVNode, Comment, Fragment, mergeProps } from "vue";
+/** Slot content with its fragments flattened (`v-for`, `<template>`), as Reka UI's `Slot` reads it. */
+function flatten(children) {
+    return children.flatMap(child => child.type === Fragment && Array.isArray(child.children)
+        ? flatten(child.children)
+        : [child]);
+}
+/**
+ * Renders your own element in place of the adapter's `div`, Reka UI's `Slot`
+ * algorithm: the first child that isn't a comment, cloned with `attrs` merged
+ * into its props (its own props win, classes and styles combine, handlers
+ * chain) and `forced` on top, its own ref kept and `ref` (when given) added.
+ */
+export function renderAsChild(children, attrs, forced, ref) {
+    if (children === undefined) {
+        return null;
+    }
+    const flat = flatten(children);
+    const index = flat.findIndex(child => child.type !== Comment);
+    const child = flat[index];
+    if (child === undefined) {
+        return flat;
+    }
+    // The child's own ref lives on the vnode, which the clone keeps.
+    const { ref: _ref, ref_key: _key, ref_for: _for, ...own } = child.props ?? {};
+    const props = mergeProps(attrs, own, forced);
+    if (ref !== undefined) {
+        props.ref = ref;
+    }
+    const cloned = cloneVNode({ ...child, props: {} }, props, true);
+    if (flat.length === 1) {
+        return cloned;
+    }
+    flat[index] = cloned;
+    return flat;
+}

package/dist/gridComponent.d.ts

@@ -0,0 +1,67 @@
+import { type DefineSetupFnComponent } from "vue";
+import type { GridConfig } from "typed-grid-areas";
+/** Props of a slot component (`<Card.icon>`) and of a grid component (`<Card>`). */
+export type SlotComponentProps = {
+    /**
+     * Render your own single child element as the slot (or grid) instead of a
+     * `div`, with the attributes merged onto it (`as-child` in templates).
+     */
+    asChild?: boolean;
+};
+/** The props of a grid component (`<Card>`). */
+export type GridComponentProps = SlotComponentProps;
+/** A slot component (`<Card.icon>`): renders the element that fills one area. */
+export type SlotComponent = DefineSetupFnComponent<SlotComponentProps>;
+/**
+ * The component a definition renders as: the grid itself, with a member
+ * component per area, named exactly like the area. An area nested through
+ * `nest` is the nested grid's component instead, with that grid's members
+ * (`<Card.content.icon>`).
+ */
+export type GridComponent<TAreaName extends string, TNest = {}> = DefineSetupFnComponent<GridComponentProps> & {
+    readonly [K in TAreaName]: K extends keyof TNest ? TNest[K] : SlotComponent;
+};
+/** Any grid component, whatever its areas. */
+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 of `Content`.
+     */
+    nest?: {
+        readonly [K in TAreaName]?: AnyGridComponent;
+    };
+};
+/**
+ * Names Vue reads on a component, so an area member named like one would
+ * change how the component behaves.
+ */
+declare const RESERVED_AREA_NAMES: readonly ["length", "props", "emits", "slots", "inheritAttrs", "displayName", "compatConfig"];
+/** An area name Vue reserves on a component: one of `RESERVED_AREA_NAMES`, or any starting with `__`. */
+export type ReservedAreaName = (typeof RESERVED_AREA_NAMES)[number] | `__${string}`;
+/**
+ * Rejects a definition with a reserved area name at compile time: the
+ * definition must then have a property it can't have, named after the problem.
+ */
+type WithoutReservedAreas<TAreaName extends string> = [
+    Extract<TAreaName, ReservedAreaName>
+] extends [never] ? unknown : {
+    [K in `area "${Extract<TAreaName, ReservedAreaName>}" is reserved by Vue; rename it`]: never;
+};
+/**
+ * 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 on the page;
+ * `<Card.icon>` renders the slot that fills the `icon` area. Both take
+ * `class`, `style`, any other attribute, and `as-child` to make your own
+ * element the slot (or grid).
+ *
+ * Bind it in `<script setup>` (or return it from `setup()`), so templates can
+ * use its members as tags. Create it once per definition.
+ */
+export declare function createGridComponent<TAreaName extends string, const TNest extends GridComponentOptions<TAreaName>["nest"] = {}>(definition: GridConfig<TAreaName> & WithoutReservedAreas<TAreaName>, options?: {
+    nest?: TNest;
+}): GridComponent<TAreaName, TNest>;
+export {};

package/dist/gridComponent.js

@@ -0,0 +1,123 @@
+import { defineComponent, h, onMounted, onUpdated, ref, } from "vue";
+import { createSlotCheck, gridMarkup, isDevelopment } from "typed-grid-areas/adapter";
+import { renderAsChild } from "./asChild.js";
+import { useGridStyle } from "./gridStyles.js";
+/**
+ * Names Vue reads on a component, so an area member named like one would
+ * change how the component behaves.
+ */
+const RESERVED_AREA_NAMES = [
+    "length",
+    "props",
+    "emits",
+    "slots",
+    "inheritAttrs",
+    "displayName",
+    "compatConfig",
+];
+function isReserved(area) {
+    return area.startsWith("__") || RESERVED_AREA_NAMES.includes(area);
+}
+/** The stateful component behind a grid component: renders the grid and puts its CSS on the page. */
+function createGrid(definition) {
+    const markup = gridMarkup(definition);
+    return defineComponent({
+        name: "Grid",
+        inheritAttrs: false,
+        props: {
+            asChild: Boolean,
+            /** The area of an outer grid this grid fills, when it is nested. */
+            dataArea: String,
+        },
+        setup(props, { attrs, slots }) {
+            useGridStyle(definition);
+            // In development, check the slots after mounting and after every update.
+            const gridRef = ref(null);
+            if (isDevelopment()) {
+                const checkSlots = createSlotCheck(definition, {
+                    strayChildRemedy: "make it a slot with as-child",
+                });
+                const check = () => {
+                    if (gridRef.value !== null) {
+                        for (const warning of checkSlots(gridRef.value)) {
+                            // eslint-disable-next-line no-console
+                            console.warn(warning);
+                        }
+                    }
+                };
+                onMounted(check);
+                onUpdated(check);
+            }
+            return () => {
+                const { sizeContainer, grid } = markup.elements(props.dataArea);
+                const gridElement = props.asChild
+                    ? renderAsChild(slots.default?.(), attrs, grid.attributes, gridRef)
+                    : h("div", { ...attrs, ...grid.attributes, ref: gridRef }, slots.default?.());
+                return sizeContainer === undefined
+                    ? gridElement
+                    : h("div", { ...sizeContainer.attributes, style: sizeContainer.style }, [gridElement]);
+            };
+        },
+    });
+}
+function createSlotComponent(area) {
+    return defineComponent({
+        name: `${area}Area`,
+        inheritAttrs: false,
+        props: { asChild: Boolean },
+        setup(props, { attrs, slots }) {
+            return () => props.asChild
+                ? renderAsChild(slots.default?.(), attrs, { "data-area": area })
+                : h("div", { ...attrs, "data-area": area }, slots.default?.());
+        },
+    });
+}
+/**
+ * A functional component rendering `component` with the attributes it is
+ * given (and `extra` on top), passing its slots through. Its own properties
+ * stay free for the area members: Vue reads none but the reserved ones.
+ */
+function passThrough(component, extra = {}) {
+    const render = (_props, { attrs, slots }) => h(component, { ...attrs, ...extra }, slots);
+    render.inheritAttrs = false;
+    return render;
+}
+/** The members (one per area) a grid component carries. */
+const MEMBERS = Symbol("typed-grid-areas members");
+/** Defines `members` on a component; `defineProperty`, since a function's `name` is read-only. */
+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 on the page;
+ * `<Card.icon>` renders the slot that fills the `icon` area. Both take
+ * `class`, `style`, any other attribute, and `as-child` to make your own
+ * element the slot (or grid).
+ *
+ * Bind it in `<script setup>` (or return it from `setup()`), so templates can
+ * use its members as tags. Create it once per definition.
+ */
+export function createGridComponent(definition, options = {}) {
+    const members = {};
+    for (const area of definition.areas) {
+        if (isReserved(area)) {
+            throw new Error(`typed-grid-areas: the area name "${area}" is reserved by Vue on a component, so it ` +
+                `can't be a member of the grid component. Rename the area.`);
+        }
+    }
+    for (const area of definition.areas) {
+        const nested = options.nest?.[area];
+        members[area] =
+            nested === undefined
+                ? createSlotComponent(area)
+                : withMembers(passThrough(nested, { "data-area": area }), nested[MEMBERS] ?? {});
+    }
+    return withMembers(passThrough(createGrid(definition)), members);
+}

package/dist/gridStyles.d.ts

@@ -0,0 +1,20 @@
+import type { GridConfig } from "typed-grid-areas";
+/**
+ * Puts a definition's CSS on the page, from a component's `setup`: into the
+ * current request's SSR context when server rendering, into `<head>` in the
+ * browser.
+ */
+export declare function useGridStyle(definition: GridConfig<string>): void;
+/**
+ * The style tags of every definition rendered with an SSR context, one per
+ * definition, as HTML for the server-rendered `<head>`. In the browser each
+ * grid then finds its tag and adds no second one.
+ *
+ * @example
+ * ```js
+ * const ctx = {};
+ * const html = await renderToString(app, ctx);
+ * head += renderGridStyles(ctx);
+ * ```
+ */
+export declare function renderGridStyles(ssrContext: object): string;

package/dist/gridStyles.js

@@ -0,0 +1,44 @@
+/**
+ * Putting definitions' CSS on the page (ADR 0005). Vue has no API for
+ * `<head>`, so in the browser each grid inserts its definition's tag itself,
+ * and on the server it registers its definition in the request's SSR
+ * context, for the app's server entry to render with `renderGridStyles`.
+ */
+import { inject, ssrContextKey } from "vue";
+import { gridStyleTags, insertGridStyle } from "typed-grid-areas/adapter";
+/**
+ * Where a request's definitions are kept on its SSR context. `Symbol.for`, so
+ * a second copy of this package (one bundled into the app, one external)
+ * still finds them.
+ */
+const DEFINITIONS = Symbol.for("typed-grid-areas/vue definitions");
+/**
+ * Puts a definition's CSS on the page, from a component's `setup`: into the
+ * current request's SSR context when server rendering, into `<head>` in the
+ * browser.
+ */
+export function useGridStyle(definition) {
+    // `inject` with a default, since the context is only provided on the server.
+    const ssrContext = inject(ssrContextKey, null);
+    if (ssrContext !== null) {
+        (ssrContext[DEFINITIONS] ??= new Set()).add(definition);
+    }
+    else if (typeof document !== "undefined") {
+        insertGridStyle(document, definition);
+    }
+}
+/**
+ * The style tags of every definition rendered with an SSR context, one per
+ * definition, as HTML for the server-rendered `<head>`. In the browser each
+ * grid then finds its tag and adds no second one.
+ *
+ * @example
+ * ```js
+ * const ctx = {};
+ * const html = await renderToString(app, ctx);
+ * head += renderGridStyles(ctx);
+ * ```
+ */
+export function renderGridStyles(ssrContext) {
+    return gridStyleTags(ssrContext[DEFINITIONS] ?? []);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createGridComponent, type GridComponent, type GridComponentOptions, type GridComponentProps, type SlotComponent, type SlotComponentProps, } from "./gridComponent.ts";
+export { renderGridStyles } from "./gridStyles.ts";

package/dist/index.js

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

package/package.json

@@ -1 +1,52 @@
-{"name":"@typed-grid-areas/vue","version":"0.0.0"}
+{
+  "name": "@typed-grid-areas/vue",
+  "version": "0.1.0",
+  "description": "Vue 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/vue"
+  },
+  "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",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build && 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": "node scripts/vue-tsc.cjs --noEmit"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.0"
+  },
+  "dependencies": {
+    "typed-grid-areas": "^0.2.0"
+  },
+  "devDependencies": {
+    "@typed-grid-areas/acceptance": "*",
+    "@types/node": "^22.10.5",
+    "@vitejs/plugin-vue": "^6.0.10",
+    "@vitest/browser-playwright": "^5.0.1",
+    "happy-dom": "^20.14.5",
+    "playwright": "^1.64.1",
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.1",
+    "vitest-browser-vue": "^3.1.0",
+    "vue": "^3.5.44",
+    "vue-tsc": "^3.3.13"
+  }
+}