@makinbakin/sdk 0.0.0-bootstrap.0

package/slots/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `@bakin/sdk/slots` — client-side slot registry + `<Slot>` primitive.
+ *
+ * The slot system lets a plugin render components contributed by other
+ * plugins at a named extension point. Today it's used for:
+ *   - `asset-preview`  — renderer for an asset (images/video/audio/pdf/...)
+ *   - `task-sidebar`   — side panels on the task detail dialog
+ *   - `home-widget`    — dashboard tiles
+ *
+ * Design:
+ *   - `registerSlot(name, Component, order?, owner?)` mutates a browser-
+ *     global Map. Namespaced under `__bakinSlotRegistry` so HMR / module
+ *     dedup doesn't wipe the registrations. `owner` is the pluginId that
+ *     registered the entry — used by `unregisterPlugin` to clean up only
+ *     that plugin's entries during hot-swap.
+ *   - `<Slot name="..." {...props} />` reads the registry at render time and
+ *     renders every matched component in `order` sequence.
+ *
+ * Registration happens at plugin client-module load time (import side effect).
+ * Test-only helpers are not exported — tests use the public unregister path.
+ */
+import { type ComponentType, type JSX } from 'react';
+interface SlotEntry {
+    component: ComponentType<Record<string, unknown>>;
+    order: number;
+    owner?: string;
+}
+/**
+ * Register a component for a named slot. Lower `order` renders first; entries
+ * with the same order render in registration order. Default `order` is 100.
+ * `owner` is the pluginId for teardown-on-hot-swap; omit in test setups.
+ */
+export declare function registerSlot<TProps>(name: string, component: ComponentType<TProps>, order?: number, owner?: string): void;
+/**
+ * Read the registered entries for a slot. Exported for tooling / tests.
+ */
+export declare function getSlotEntries(name: string): ReadonlyArray<SlotEntry>;
+/**
+ * Remove every slot entry owned by the given plugin. Used by
+ * `unregisterPlugin` during v2 hot-swap. Entries without an `owner`
+ * (test registrations, pre-v2 legacy registrations) survive — callers
+ * that want to wipe unowned entries should re-register them after.
+ */
+export declare function clearSlotsOwnedBy(pluginId: string): void;
+interface SlotProps {
+    name: string;
+    [key: string]: unknown;
+}
+/**
+ * Render all components registered for the named slot, in order. Extra props
+ * are passed through to every registered component unchanged. Returns `null`
+ * if nothing is registered.
+ */
+export declare function Slot({ name, ...props }: SlotProps): JSX.Element | null;
+export {};

package/slots/index.js

@@ -0,0 +1,92 @@
+// @bun
+// packages/sdk/src/slots/index.tsx
+import { useSyncExternalStore } from "react";
+
+// packages/sdk/src/register.ts
+"use client";
+function buildNavItemsSnapshot(registry) {
+  const items = [];
+  for (const navItems of registry.navByPlugin.values()) {
+    items.push(...navItems);
+  }
+  return items.sort((a, b) => (a.order ?? 100) - (b.order ?? 100));
+}
+function getRegistry() {
+  const g = globalThis;
+  if (!g.__bakinClientRegistry) {
+    g.__bakinClientRegistry = {
+      navByPlugin: new Map,
+      routesByPlugin: new Map,
+      cleanupByPlugin: new Map,
+      navItemsSnapshot: [],
+      version: 0,
+      listeners: new Set
+    };
+  }
+  const registry = g.__bakinClientRegistry;
+  if (!Array.isArray(registry.navItemsSnapshot)) {
+    registry.navItemsSnapshot = buildNavItemsSnapshot(registry);
+  }
+  return registry;
+}
+function getRegistryVersion() {
+  return getRegistry().version;
+}
+function subscribeRegistry(listener) {
+  const registry = getRegistry();
+  registry.listeners.add(listener);
+  return () => {
+    registry.listeners.delete(listener);
+  };
+}
+
+// packages/sdk/src/slots/index.tsx
+import { jsxDEV, Fragment } from "react/jsx-dev-runtime";
+"use client";
+function getRegistry2() {
+  const g = globalThis;
+  if (!g.__bakinSlotRegistry) {
+    g.__bakinSlotRegistry = new Map;
+  }
+  return g.__bakinSlotRegistry;
+}
+function registerSlot(name, component, order = 100, owner) {
+  const reg = getRegistry2();
+  const entries = reg.get(name) ?? [];
+  entries.push({ component, order, owner });
+  entries.sort((a, b) => a.order - b.order);
+  reg.set(name, entries);
+}
+function getSlotEntries(name) {
+  return getRegistry2().get(name) ?? [];
+}
+function clearSlotsOwnedBy(pluginId) {
+  const reg = getRegistry2();
+  for (const [name, entries] of reg.entries()) {
+    const filtered = entries.filter((e) => e.owner !== pluginId);
+    if (filtered.length === 0)
+      reg.delete(name);
+    else
+      reg.set(name, filtered);
+  }
+}
+function Slot({ name, ...props }) {
+  useSyncExternalStore(subscribeRegistry, getRegistryVersion, getRegistryVersion);
+  const entries = getSlotEntries(name);
+  if (entries.length === 0)
+    return null;
+  return /* @__PURE__ */ jsxDEV(Fragment, {
+    children: entries.map((entry, i) => {
+      const C = entry.component;
+      return /* @__PURE__ */ jsxDEV(C, {
+        ...props
+      }, `${name}-${i}`, false, undefined, this);
+    })
+  }, undefined, false, undefined, this);
+}
+export {
+  registerSlot,
+  getSlotEntries,
+  clearSlotsOwnedBy,
+  Slot
+};