@toyonix/web-kit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ToYoNiX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @toyonix/web-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared design system, components, and tooling for toyonix static sites (Next.js static export on
+GitHub Pages). New sites should start from the `web-starter` template, which wires all of this up.
+
+## Setup
+
+```ts
+// next.config.ts
+import { withWebKit } from "@toyonix/web-kit/next";
+export default withWebKit({}); // static export, basePath from the repo name
+```
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@toyonix/web-kit/tailwind.css";
+```
+
+```tsx
+// app/layout.tsx
+import { AppShell, ThemeScript } from "@toyonix/web-kit/react";
+import { getRegistrySnapshot } from "@toyonix/web-kit/registry";
+import "./globals.css";
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <ThemeScript />
+      </head>
+      <body>
+        <AppShell registry={await getRegistrySnapshot()}>{children}</AppShell>
+      </body>
+    </html>
+  );
+}
+```
+
+Configs: `export { default } from "@toyonix/web-kit/eslint"` (eslint.config.mjs),
+`export { default } from "@toyonix/web-kit/prettier"` (prettier.config.mjs), and
+`"extends": "@toyonix/web-kit/tsconfig.json"`.
+
+## Entry points
+
+| Import                                                   | What                                                            |
+| -------------------------------------------------------- | --------------------------------------------------------------- |
+| `@toyonix/web-kit`                                       | `withBasePath`, `appHref`, `getAppId`, slugs, theme helpers     |
+| `@toyonix/web-kit/react`                                 | `AppShell`, `ThemeScript`, `useTheme`, components               |
+| `@toyonix/web-kit/storage`                               | namespaced `storage.app` / `storage.session` / `storage.shared` |
+| `@toyonix/web-kit/registry`                              | registry types, `getRegistrySnapshot`, `fetchRegistry`          |
+| `@toyonix/web-kit/registry/build`                        | `buildRegistry` (root site only, Node)                          |
+| `@toyonix/web-kit/next`                                  | `withWebKit` for next.config                                    |
+| `@toyonix/web-kit/css`                                   | all CSS without Tailwind (works in plain HTML)                  |
+| `@toyonix/web-kit/tailwind.css`                          | all CSS + Tailwind theme mapped to the tokens                   |
+| `@toyonix/web-kit/eslint`, `/prettier`, `/tsconfig.json` | shared configs                                                  |
+
+## Rules for sites
+
+- Use tokens (`bg-surface`, `text-accent-text`, `var(--tx-accent)`), never hard-coded colors.
+  Tailwind's default palette is removed on purpose.
+- Use `storage` for localStorage/sessionStorage/IndexedDB names; every app shares one origin.
+- In-app links: `next/link`. Links to other toyonix apps: `<AppLink app="gen">` or `appHref()`.
+- Don't copy kit components into a site. If something is missing, add it to the kit.
+
+## License
+
+MIT. Bundled fonts (Newsreader, Space Grotesk, Space Mono) are under the SIL Open Font License
+1.1; see `dist/css/fonts/LICENSE-*.txt`.

package/config/eslint.js

@@ -0,0 +1,68 @@
+// @toyonix/web-kit/eslint: shared ESLint flat config for toyonix sites.
+//
+//   // eslint.config.mjs
+//   export { default } from "@toyonix/web-kit/eslint";
+//
+// Next core-web-vitals + TypeScript (including type-aware rules), plus the platform rules:
+// storage only through the kit (spec §6) and no deep imports into the kit.
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+import tseslint from "typescript-eslint";
+
+const STORAGE_MESSAGE =
+  "All toyonix apps share one origin. Use `storage` from @toyonix/web-kit/storage so keys stay namespaced.";
+const COOKIE_MESSAGE =
+  "All toyonix apps share one origin. If you really need a cookie, set Path=cookiePath() from @toyonix/web-kit/storage and disable this rule on that line.";
+
+/** The toyonix platform rules on their own, for composing a custom config. */
+export const platformRules = defineConfig({
+  name: "toyonix/platform",
+  rules: {
+    // toyonix sites use the App Router; this rule only knows pages/ and warns when it is missing.
+    "@next/next/no-html-link-for-pages": "off",
+    "no-restricted-globals": [
+      "error",
+      ...["localStorage", "sessionStorage", "indexedDB"].map((name) => ({ name, message: STORAGE_MESSAGE })),
+    ],
+    "no-restricted-properties": [
+      "error",
+      ...["localStorage", "sessionStorage", "indexedDB"].flatMap((property) =>
+        ["window", "globalThis", "self"].map((object) => ({ object, property, message: STORAGE_MESSAGE })),
+      ),
+      { object: "document", property: "cookie", message: COOKIE_MESSAGE },
+    ],
+    "no-restricted-imports": [
+      "error",
+      {
+        patterns: [
+          {
+            group: ["@toyonix/web-kit/dist/*", "@toyonix/web-kit/src/*"],
+            message:
+              "Import from @toyonix/web-kit's public entry points only; internals change without notice.",
+          },
+        ],
+      },
+    ],
+  },
+});
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  {
+    name: "toyonix/type-aware",
+    files: ["**/*.{ts,tsx,mts,cts}"],
+    extends: [tseslint.configs.recommendedTypeCheckedOnly],
+    languageOptions: { parserOptions: { projectService: true } },
+  },
+  platformRules,
+  globalIgnores([
+    "**/.next/**",
+    "**/out/**",
+    "**/build/**",
+    "**/dist/**",
+    "**/coverage/**",
+    "**/next-env.d.ts",
+  ]),
+]);

package/config/prettier.js

@@ -0,0 +1,20 @@
+// @toyonix/web-kit/prettier: shared Prettier config for toyonix sites.
+//
+//   // prettier.config.mjs
+//   export { default } from "@toyonix/web-kit/prettier";
+//
+// The Tailwind plugin sorts class names; it reads the theme from app/globals.css by default.
+import * as tailwind from "prettier-plugin-tailwindcss";
+
+/** Builds the config, e.g. when the Tailwind entry stylesheet lives somewhere other than app/globals.css. */
+export function createPrettierConfig({ tailwindStylesheet = "./app/globals.css" } = {}) {
+  /** @type {import("prettier").Config & { tailwindStylesheet?: string }} */
+  const config = {
+    printWidth: 110,
+    plugins: [tailwind],
+    tailwindStylesheet,
+  };
+  return config;
+}
+
+export default createPrettierConfig();

package/config/tsconfig.base.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "display": "@toyonix/web-kit site base",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["DOM", "DOM.Iterable", "ES2023"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "allowJs": false,
+    "noEmit": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }]
+  }
+}

package/dist/css/base.css

@@ -0,0 +1,58 @@
+/*
+ * Element defaults. Loaded in the `base` cascade layer, so Tailwind utilities and app CSS
+ * always win. Sizes and margins are left to components (.tx-display, .tx-prose, …) so plain
+ * elements stay predictable.
+ */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  margin: 0;
+  background-color: var(--tx-bg);
+  color: var(--tx-text);
+  font-family: var(--tx-font-sans);
+  font-size: 16px;
+  line-height: 1.6;
+  -webkit-font-smoothing: antialiased;
+}
+
+h1,
+h2,
+h3,
+h4 {
+  font-family: var(--tx-font-heading);
+  font-weight: var(--tx-heading-weight);
+  letter-spacing: var(--tx-heading-tracking);
+  text-transform: var(--tx-heading-transform);
+  line-height: 1.15;
+}
+
+a {
+  color: var(--tx-accent-text);
+  text-underline-offset: 3px;
+}
+
+code,
+kbd,
+pre,
+samp {
+  font-family: var(--tx-font-mono);
+}
+
+::selection {
+  background: var(--tx-accent);
+  color: var(--tx-accent-contrast);
+}
+
+:focus-visible {
+  outline: var(--tx-border-width) solid var(--tx-ring);
+  outline-offset: 2px;
+}