@arcote.tech/platform 0.4.1

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@arcote.tech/platform",
+  "type": "module",
+  "version": "0.4.1",
+  "private": false,
+  "author": "Przemysław Krasiński [arcote.tech]",
+  "description": "Arc Platform — module system, router, layout, theme, i18n, platform app shell",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@arcote.tech/arc-ds": "workspace:*",
+    "@arcote.tech/arc-react": "workspace:*"
+  },
+  "peerDependencies": {
+    "@arcote.tech/arc": "workspace:*",
+    "@lingui/core": "^5.0.0",
+    "@lingui/react": "^5.0.0",
+    "framer-motion": "^12.0.0",
+    "lucide-react": ">=0.400.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@lingui/core": "^5.9.2",
+    "@types/react": "^19.2.7",
+    "typescript": "~5.9.3"
+  }
+}

package/src/arc.ts

@@ -0,0 +1,308 @@
+import type { ComponentType, ReactNode } from "react";
+import { context as createContext, type ArcContextElementAny } from "@arcote.tech/arc";
+import { registerModule, setContext, setVariantOverrides } from "./registry";
+import type {
+  ArcComponent,
+  ArcFragment,
+  ArcModule,
+  BuiltModule,
+  ContextElementFragment,
+  ExtractPages,
+  PageFragment,
+  PageOptions,
+  SlotFragment,
+  SlotId,
+  SlotOptions,
+  WrapperFragment,
+  WrapperOptions,
+} from "./types";
+
+let moduleCounter = 0;
+let fragmentCounter = 0;
+
+function nextModuleId(): string {
+  return `mod_${++moduleCounter}`;
+}
+
+function nextFragmentId(prefix: string): string {
+  return `${prefix}_${++fragmentCounter}`;
+}
+
+function isImpl(this: { types: readonly string[] }, type: string): boolean {
+  return this.types.includes(type);
+}
+
+/**
+ * Detect if a value is an ArcContext (has elements array + elementMap).
+ */
+function isArcContext(value: unknown): boolean {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    "elements" in value &&
+    "elementMap" in value &&
+    Array.isArray((value as any).elements)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Standalone fragment factories
+// ---------------------------------------------------------------------------
+
+export function page<TPath extends string>(
+  path: TPath,
+  component: ArcComponent,
+  options: PageOptions = {},
+): PageFragment<TPath> {
+  return {
+    id: options.id ?? nextFragmentId("page"),
+    moduleId: "",
+    types: ["page"] as const,
+    is: isImpl,
+    path,
+    component,
+    layout: options.layout,
+    icon: options.icon,
+    label: options.label,
+    tooltip: options.tooltip,
+    children: options.children,
+  };
+}
+
+export function wrapper(
+  component: ComponentType<{ children: ReactNode }>,
+  options: WrapperOptions = {},
+): WrapperFragment {
+  const { id, order, after, before } = options;
+  return {
+    id: id ?? nextFragmentId("wrap"),
+    moduleId: "",
+    types: ["wrapper"] as const,
+    is: isImpl,
+    component,
+    ordering: { order: order ?? 0, after, before },
+  };
+}
+
+export function slot(
+  slotId: SlotId | string,
+  component: ArcComponent,
+  options: SlotOptions = {},
+): SlotFragment {
+  const { id, order, after, before } = options;
+  return {
+    id: id ?? nextFragmentId("slot"),
+    moduleId: "",
+    types: ["slot"] as const,
+    is: isImpl,
+    slotId: slotId as SlotId,
+    component,
+    ordering: { order: order ?? 0, after, before },
+  };
+}
+
+export function contextElement(
+  element: ArcContextElementAny,
+): ContextElementFragment {
+  return {
+    id: element.name,
+    moduleId: "",
+    types: ["context-element"] as const,
+    is: isImpl,
+    element,
+  };
+}
+
+/**
+ * Convert all elements from a context into ContextElementFragments.
+ *
+ * Shorthand for `context.elements.map(contextElement)`.
+ *
+ * @example
+ * ```typescript
+ * module("auth")
+ *   .private([
+ *     ...contextFragments(authContext),
+ *     wrapper(AuthProvider, { order: 0 }),
+ *   ])
+ *   .build();
+ * ```
+ */
+export function contextFragments(
+  ctx: { elements: readonly ArcContextElementAny[] },
+): ContextElementFragment[] {
+  return ctx.elements.map(contextElement);
+}
+
+// ---------------------------------------------------------------------------
+// module() — primary API for creating Arc modules
+// ---------------------------------------------------------------------------
+
+class ModuleBuilder<
+  TPages = {},
+  TCtx = undefined,
+  TScope extends string | undefined = undefined,
+> {
+  private _public: ArcFragment[] = [];
+  private _private: ArcFragment[] = [];
+  private _pages: Record<string, string> | undefined;
+  private _ctx: { elements: readonly ArcContextElementAny[] } | undefined;
+  private _scope: string | undefined;
+
+  constructor(readonly name: string) {}
+
+  /**
+   * Register the module's ArcContext and scope name.
+   * Context element fragments are auto-injected in build().
+   */
+  context<C extends { elements: readonly ArcContextElementAny[] }, S extends string>(
+    ctx: C,
+    scope: S,
+  ): ModuleBuilder<TPages, C, S> {
+    this._ctx = ctx;
+    this._scope = scope;
+    return this as unknown as ModuleBuilder<TPages, C, S>;
+  }
+
+  /**
+   * Register public fragments.
+   *
+   * Array: existing behavior, no named pages.
+   * Record: keys become `pages.*` on the built module.
+   */
+  public(fragments: ArcFragment[]): ModuleBuilder<TPages, TCtx, TScope>;
+  public<R extends Record<string, PageFragment<string>>>(
+    pages: R,
+  ): ModuleBuilder<ExtractPages<R>, TCtx, TScope>;
+  public(input: ArcFragment[] | Record<string, PageFragment<string>>): ModuleBuilder<any, TCtx, TScope> {
+    if (Array.isArray(input)) {
+      this._public = input;
+    } else {
+      const pages: Record<string, string> = {};
+      const fragments: ArcFragment[] = [];
+      for (const [key, frag] of Object.entries(input)) {
+        pages[key] = frag.path;
+        fragments.push(frag);
+      }
+      this._public = fragments;
+      this._pages = pages;
+    }
+    return this;
+  }
+
+  private(fragments: ArcFragment[]): this {
+    this._private = fragments;
+    return this;
+  }
+
+  build(): BuiltModule<TPages, TCtx, TScope>;
+  build<D extends Record<string, unknown>>(domain: D): BuiltModule<TPages, TCtx, TScope> & Readonly<D>;
+  build(domain?: Record<string, unknown>) {
+    const moduleId = nextModuleId();
+
+    // Auto-inject context element fragments when .context() was called
+    if (this._ctx) {
+      const ctxFrags = contextFragments(this._ctx);
+      this._private = [...ctxFrags, ...this._private];
+    }
+
+    const allFragments = [...this._public, ...this._private];
+
+    // Assign moduleId to all fragments
+    for (const f of allFragments) {
+      (f as { moduleId: string }).moduleId = moduleId;
+    }
+
+    // Auto-extract and register context from context-element fragments
+    const contextElements = allFragments
+      .filter((f): f is ContextElementFragment => f.is("context-element"))
+      .map((f) => f.element);
+
+    if (contextElements.length > 0) {
+      const ctx = createContext(contextElements);
+      setContext(ctx);
+    }
+
+    const mod: Record<string, unknown> = {
+      id: moduleId,
+      fragments: allFragments,
+      publicFragments: this._public,
+      pages: Object.freeze(this._pages ?? {}),
+    };
+    if (this._ctx !== undefined) mod.context = this._ctx;
+    if (this._scope !== undefined) mod.scope = this._scope;
+    if (domain) Object.assign(mod, domain);
+
+    registerModule(mod as unknown as ArcModule);
+    return mod;
+  }
+}
+
+export function module(name: string): ModuleBuilder {
+  return new ModuleBuilder(name);
+}
+
+// ---------------------------------------------------------------------------
+// arc() — deprecated, use module() instead
+// ---------------------------------------------------------------------------
+
+/**
+ * @deprecated Use module("name").public([]).private([]).build() instead.
+ */
+export function arc(
+  factory: (methods: {
+    slot: (slotId: SlotId | string, component: ArcComponent, options?: SlotOptions) => SlotFragment;
+    page: <TPath extends string>(path: TPath, component: ArcComponent, options?: PageOptions) => PageFragment<TPath>;
+    wrapper: (component: ComponentType<{ children: ReactNode }>, options?: WrapperOptions) => WrapperFragment;
+  }) => ArcFragment[] | void,
+): ArcModule {
+  const moduleId = nextModuleId();
+  const allFragments: ArcFragment[] = [];
+
+  const methods = {
+    slot: (slotId: SlotId | string, component: ArcComponent, options: SlotOptions = {}): SlotFragment => {
+      const f = slot(slotId, component, options);
+      (f as { moduleId: string }).moduleId = moduleId;
+      allFragments.push(f);
+      return f;
+    },
+    page: <TPath extends string>(path: TPath, component: ArcComponent, options: PageOptions = {}): PageFragment<TPath> => {
+      const f = page(path, component, options);
+      (f as { moduleId: string }).moduleId = moduleId;
+      allFragments.push(f);
+      return f;
+    },
+    wrapper: (component: ComponentType<{ children: ReactNode }>, options: WrapperOptions = {}): WrapperFragment => {
+      const f = wrapper(component, options);
+      (f as { moduleId: string }).moduleId = moduleId;
+      allFragments.push(f);
+      return f;
+    },
+  };
+
+  const result = factory(methods);
+
+  // Context registration: factory returned an ArcContext
+  if (isArcContext(result)) {
+    setContext(result);
+    return { id: moduleId, fragments: [], publicFragments: [] };
+  }
+
+  const publicFragments: readonly ArcFragment[] = Array.isArray(result) ? result : [];
+  const mod: ArcModule = {
+    id: moduleId,
+    fragments: allFragments,
+    publicFragments,
+  };
+  registerModule(mod);
+  return mod;
+}
+
+/**
+ * Register DS variant overrides from a module.
+ */
+arc.variants = (
+  overrides: Record<string, Record<string, Record<string, string>>>,
+): void => {
+  setVariantOverrides(overrides);
+};

package/src/hooks/use-title.ts

@@ -0,0 +1,11 @@
+import { useEffect } from "react";
+
+export function useTitle(title: string) {
+  useEffect(() => {
+    const prev = document.title;
+    document.title = title;
+    return () => {
+      document.title = prev;
+    };
+  }, [title]);
+}

package/src/i18n.tsx

@@ -0,0 +1,76 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+
+interface I18nState {
+  locale: string;
+  messages: Record<string, string>;
+  setLocale: (locale: string) => void;
+  locales: Record<string, string>;
+}
+
+const I18nContext = createContext<I18nState | null>(null);
+
+export interface I18nProviderProps {
+  children: ReactNode;
+  defaultLocale: string;
+  locales: Record<string, string>;
+  loadMessages: (locale: string) => Promise<Record<string, string>>;
+}
+
+export function I18nProvider({
+  children,
+  defaultLocale,
+  locales,
+  loadMessages,
+}: I18nProviderProps) {
+  const [locale, setLocaleRaw] = useState(() => {
+    try {
+      const saved = localStorage.getItem("arc-locale");
+      if (saved && saved in locales) return saved;
+    } catch {}
+    return defaultLocale;
+  });
+  const [messages, setMessages] = useState<Record<string, string>>({});
+
+  const setLocale = useCallback(
+    async (newLocale: string) => {
+      const msgs = await loadMessages(newLocale);
+      setMessages(msgs);
+      setLocaleRaw(newLocale);
+      try { localStorage.setItem("arc-locale", newLocale); } catch {}
+    },
+    [loadMessages],
+  );
+
+  useEffect(() => {
+    setLocale(locale);
+  }, []);
+
+  return (
+    <I18nContext.Provider value={{ locale, messages, setLocale, locales }}>
+      {children}
+    </I18nContext.Provider>
+  );
+}
+
+export function useI18n() {
+  const ctx = useContext(I18nContext);
+  if (!ctx) throw new Error("useI18n must be used within I18nProvider");
+  return ctx;
+}
+
+export function Trans({ children }: { children?: ReactNode }) {
+  const ctx = useContext(I18nContext);
+  if (!ctx || typeof children !== "string") return <>{children}</>;
+  return <>{ctx.messages[children] || children}</>;
+}
+
+export function t(strings: TemplateStringsArray, ...values: any[]) {
+  return String.raw(strings, ...values);
+}

package/src/index.ts

@@ -0,0 +1,121 @@
+// Arc Platform — public API
+
+// Module system
+export { module, page, wrapper, slot, contextElement, contextFragments } from "./arc";
+/** @deprecated Use module() instead */
+export { arc } from "./arc";
+export {
+  clearModules,
+  clearRegistry,
+  getAllFragments,
+  getAllModules,
+  getContext,
+  getContextElementFragments,
+  getDefaultLayout,
+  getModule,
+  getPageByPath,
+  getPageFragments,
+  getSlotFragments,
+  getVariantOverrides,
+  getWrapperFragments,
+  registerModule,
+  setContext,
+  setDefaultLayout,
+  setVariantOverrides,
+  subscribe,
+  subscribeContext,
+  unregisterModule,
+} from "./registry";
+
+// Layout (re-exported from arc-ds)
+export {
+  arcTransitions,
+  DragHandle,
+  DynamicSlotProvider,
+  ExpandablePanel,
+  Layout,
+  OverlayProvider,
+  ScrollNav,
+  SubNavShell,
+  ToolbarExpandProvider,
+  useExpandable,
+  useDynamicSlotContent,
+  useOverlay,
+  useSlotContent,
+  useToolbarExpand,
+  Z,
+} from "@arcote.tech/arc-ds";
+export type {
+  SubNavShellProps,
+  SubNavTab,
+  UseExpandableReturn,
+} from "@arcote.tech/arc-ds";
+
+// Layout (platform-specific — depends on registry/router)
+export { BlankLayout } from "./layout/blank-layout";
+export { ArcLayoutProvider } from "./layout/layout-provider";
+export type { ArcLayoutProviderProps } from "./layout/layout-provider";
+export { OverflowNav } from "./layout/overflow-nav";
+export { PageRouter } from "./layout/page-router";
+export { PageSubNavShell } from "./layout/page-sub-nav-shell";
+export { SlotRenderer } from "./layout/slot-renderer";
+export type { SlotRendererProps } from "./layout/slot-renderer";
+export { useSlotFragments } from "./layout/use-slot-fragments";
+
+// Router
+export {
+  ArcRouterProvider,
+  useArcNavigate,
+  useArcRoute,
+  useArcParams,
+  useModuleNavigate,
+} from "./router";
+
+// Theme
+export { ThemeProvider, useTheme } from "./theme";
+
+// i18n
+export { I18nProvider, Trans, t, useI18n } from "./i18n";
+export type { I18nProviderProps } from "./i18n";
+
+// Locale (Lingui) — deprecated, use I18nProvider
+export { LocaleProvider, useLocale } from "./locale";
+export type { LocaleProviderProps } from "./locale";
+
+// Hooks
+export { useTitle } from "./hooks/use-title";
+
+// Platform
+export { loadModules, reloadModules, useModuleLoader } from "./module-loader";
+export type { ModuleLoaderState, ModuleManifest } from "./module-loader";
+export { PlatformApp } from "./platform-app";
+export type { PlatformAppProps } from "./platform-app";
+export {
+  PlatformModelProvider,
+  usePlatformResetModel,
+  usePlatformScope,
+} from "./platform-context";
+
+// Types
+export type {
+  ArcComponent,
+  ArcFactory,
+  ArcFactoryMethods,
+  ArcFragment,
+  ArcLayoutComponent,
+  ArcModule,
+  BuiltModule,
+  ContextElementFragment,
+  ExtractPages,
+  FragmentOrdering,
+  PageFragment,
+  PageOptions,
+  PageShellProps,
+  PublicArcFragment,
+  PublicPaths,
+  SlotFragment,
+  SlotId,
+  SlotOptions,
+  WrapperFragment,
+  WrapperOptions,
+} from "./types";

package/src/layout/blank-layout.tsx

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+/**
+ * Blank layout — no chrome, no toolbar, just renders children.
+ * Use for pages that need full control: sign-in, onboarding, etc.
+ *
+ * @example
+ * ```typescript
+ * import { BlankLayout } from "@arcote.tech/platform";
+ * page("/sign-in", SignInPage, { layout: BlankLayout })
+ * ```
+ */
+export function BlankLayout({ children }: { children: ReactNode }) {
+  return <>{children}</>;
+}

package/src/layout/layout-provider.tsx

@@ -0,0 +1,39 @@
+import {
+  ArcRouterProvider,
+  DynamicSlotProvider,
+  OverlayProvider,
+  SlotRenderProvider,
+} from "@arcote.tech/arc-ds";
+import type { SlotRenderFn } from "@arcote.tech/arc-ds";
+import { AnimatePresence } from "framer-motion";
+import { useCallback, type ReactNode } from "react";
+import { SlotRenderer } from "./slot-renderer";
+
+export interface ArcLayoutProviderProps {
+  children: ReactNode;
+}
+
+export function ArcLayoutProvider({ children }: ArcLayoutProviderProps) {
+  const renderSlot: SlotRenderFn = useCallback(
+    (slotId, options) => (
+      <SlotRenderer
+        slotId={slotId}
+        displayMode={options?.displayMode as any}
+        className={options?.className}
+      />
+    ),
+    [],
+  );
+
+  return (
+    <ArcRouterProvider>
+      <SlotRenderProvider value={renderSlot}>
+        <OverlayProvider>
+          <DynamicSlotProvider>
+            <AnimatePresence mode="wait">{children}</AnimatePresence>
+          </DynamicSlotProvider>
+        </OverlayProvider>
+      </SlotRenderProvider>
+    </ArcRouterProvider>
+  );
+}