@trebired/frontend 8.0.0 → 8.0.1

package/README.md

@@ -1,97 +1,102 @@
-# Frontend Package
+# @trebired/frontend
 
-Generic browser runtime systems for DOM binding, actions, overlays, theme state, live refresh, inputs, upload, layout, and React rendering.
+Generic frontend framework for Trebired applications: React shell, design tokens, UI components, browser runtime, and frontend server helpers.
 
-The package owns reusable browser behavior, icon rendering, overlay/runtime primitives, layout chrome, and generic UI components. Callers own product routes, copy, storage keys, persistence, navigation, logging adapters, domain icon maps, and backend response contracts beyond the documented generic JSON shape.
+This package owns reusable layout, theme, sidebar, header, overlay, upload, flash, tab, link, icon, and boot-script behavior. Callers own product routes, copy, persistence endpoints, domain rendering, and application design values supplied through config.
 
-## Runtime
+## Install
 
-Bind the root runtime after the document shell exists:
+Runtime support: Bun 1+.
 
-```ts
-import { bindFrontendRuntime } from "<package-name>";
-
-bindFrontendRuntime(document, {
-  adapters: {
-    navigation: {
-      navigate(url) {
-        window.location.assign(url);
-      },
-    },
-  },
-});
+```sh
+bun i @trebired/frontend
 ```
 
-Feature binders such as `bindActionForms()`, `bindTooltips()`, `bindModals()`, and `bindUploads()` are idempotent and accept a `Document`, `HTMLElement`, or `DocumentFragment`.
+## Quick Start
 
-## Configuration
-
-Projects configure package-owned systems through the frontend config file consumed by the bundler.
+Configure the package through `.trebired/frontend/config.ts`:
 
 ```ts
-import { defineConfig } from "<package-name>/config";
+import { defineConfig } from "@trebired/frontend/config";
 
 export default defineConfig({
-  prefix: "tbf",
+  forVersion: "8.0.0",
   assets: {
     icons: {
       endpoint: "/__icons/svg",
-      packs: ["remixicon", "simple-icons"],
-    },
-  },
-  design: {
-    interactions: {
-      activePress: {
-        enabled: false,
-        brightness: 0.9,
-      },
-    },
-  },
-  runtime: {
-    theme: {
-      defaultMode: "dark",
-      modes: {
-        dark: { scheme: "dark" },
-        light: { scheme: "light" },
-      },
+      packs: ["remixicon"],
     },
   },
+  components: {},
+  design: {},
+  runtime: {},
   systems: {
-    actions: true,
     flash: true,
     layout: true,
-    modal: true,
     popover: true,
-    sidebar: true,
     theme: true,
   },
 });
 ```
 
-The config entrypoint exports `defineConfig()`, `normalizeFrontendConfig()`, `loadConfig()`, `findConfig()`, `generateFrontendScss()`, `collectConfigDependencies()`, and `THEME_MODE_ATTRIBUTE`.
+Bind the browser runtime after the document shell exists:
 
-## Components
+```ts
+import { bindFrontendRuntime } from "@trebired/frontend";
 
-React components render normal HTML with `data-tbf-*` attributes and `tbf-*` classes. Use the React entrypoint for package-owned default markup:
+bindFrontendRuntime(document);
+```
 
-```tsx
-import { UploadField } from "<package-name>/react";
+## Concepts
 
-export function AvatarUpload() {
-  return (
-    <UploadField
-      name="avatar"
-      accept="image/png,image/jpeg"
-      crop={true}
-      preview={true}
-      drop={true}
-    />
-  );
-}
-```
+### Package Namespace
+
+Frontend source-visible class names, data attributes, CSS variables, tokens, and events are created through `@trebired/bundler` namespace helpers. The package's own `.trebired/bundler/config.ts` declares the `tbf` prefix. Applications do not set a frontend prefix to consume this package.
+
+### React Shell
+
+The React entrypoint renders package-owned document, layout, header, sidebar, portal, upload, tabs, tooltip, popover, modal, fullscreen, flash, text-link, language, and theme controls. The markup is generic and configured through `.trebired/frontend/config.ts`.
+
+## Configuration
+
+### Design
+
+`design` config owns palette, semantic tokens, scales, active feedback, shadows, and component styling values. The package stays style-generic and does not hardcode application colors.
+
+### Runtime
+
+`runtime` config owns browser systems such as theme state, navigation hooks, boot scripts, and runtime adapters.
+
+### Systems
+
+`systems` config enables package-owned binders. Disabled systems do not emit their boot scripts.
+
+## Runtime
+
+Feature binders are idempotent and accept a `Document`, `HTMLElement`, or `DocumentFragment`. Runtime binding syncs newly added DOM without resetting document-level state such as the active theme.
+
+Frontend server helpers own package static assets, icon SVG endpoints, React document rendering support, and frontend middleware that is generic across Trebired applications.
+
+## Public API
+
+Entrypoints:
+
+- `@trebired/frontend`
+- `@trebired/frontend/config`
+- `@trebired/frontend/react`
+- `@trebired/frontend/server`
+
+The root entrypoint exports browser runtime binders and namespace helpers. The config entrypoint exports config loading, normalization, generated CSS, and dependency collection. The React entrypoint exports generic UI components. The server entrypoint exports frontend-related backend helpers.
+
+## Migration Notes
+
+Applications import public APIs only from the package root, `/config`, `/react`, and `/server`. There is no public Sass, style, or internal component subpath API.
 
-## Styling
+## What It Does Not Do
 
-There is no public Sass subpath API. Package-owned CSS is selected by the frontend config, then emitted by the config entrypoint as SCSS for the bundler to compile in memory.
+This package does not:
 
-Generic app UI such as headers, mobile nav, breadcrumb, disclosure, tabs, dropdown/search controls, graph shells, cards, canvas panels, flash messages, and sidebar link lists is available from the React entrypoint.
+- Own product routes, copy, data, or persistence policy.
+- Own application colors outside the supplied frontend config.
+- Provide compatibility bridges for removed application-local UI attributes.
+- Expose package Sass or internal component subpaths as public API.

package/dist/actions/styles/index.scss

@@ -76,6 +76,23 @@
   flex: 0 0 auto;
 }
 
+#{ns.class("button")}.icon {
+  #{ns.css-var("icon-color")}: currentColor;
+  #{ns.css-var("ui-action-current-icon")}: currentColor;
+}
+
+#{ns.class("button")}.icon > i,
+
+#{ns.class("button")}.icon > svg,
+
+#{ns.class("button")}.icon > i svg,
+
+#{ns.class("button")}.icon > [data-icon],
+
+#{ns.class("button")}.icon > [data-icon] svg {
+  color: currentColor;
+}
+
 #{ns.modifier("button", "strong")} {
   #{ns.css-var("ui-action-current-icon")}: var(
     #{ns.css-var("ui-action-tone-highlight-icon")},

package/dist/primitives/styles/_controls.scss

@@ -140,6 +140,7 @@
   }
 
   &.icon {
+    #{ns.css-var("icon-color")}: currentColor;
     display: inline-flex;
     align-items: center;
     justify-content: center;
@@ -161,6 +162,7 @@
     > img {
       display: block;
       margin: 0;
+      color: currentColor;
       flex: 0 0 auto;
       font-size: inherit;
     }

package/dist/surface/styles/index.scss

@@ -73,6 +73,23 @@
   flex: 0 0 auto;
 }
 
+#{ns.class("button")}.icon {
+  #{ns.css-var("icon-color")}: currentColor;
+  #{ns.css-var("surf-btn-current-icon")}: currentColor;
+}
+
+#{ns.class("button")}.icon > i,
+
+#{ns.class("button")}.icon > svg,
+
+#{ns.class("button")}.icon > i svg,
+
+#{ns.class("button")}.icon > [data-icon],
+
+#{ns.class("button")}.icon > [data-icon] svg {
+  color: currentColor;
+}
+
 #{ns.modifier("button", "strong")} {
   #{ns.css-var("surf-btn-current-icon")}: var(
     #{ns.css-var("surf-btn-tone-highlight-icon")},

package/package.json

@@ -1,16 +1,21 @@
 {
-  "name": "@trebired/frontend",
-  "version": "8.0.0",
-  "description": "Generic browser runtime systems for Trebired frontend packages and applications.",
-  "type": "module",
-  "private": false,
-  "license": "AGPL-3.0-only",
   "author": "Miroslav Machynka (Trebired)",
   "config": {
     "organization": {
-      "name": "trebired"
+      "displayName": "Trebired",
+      "name": "trebired",
+      "website": "https://trebired.com"
+    },
+    "creator": {
+      "name": "Miroslav Machynka"
     }
   },
+  "name": "@trebired/frontend",
+  "version": "8.0.1",
+  "description": "Generic browser runtime systems for Trebired frontend packages and applications.",
+  "type": "module",
+  "private": false,
+  "license": "AGPL-3.0-only",
   "packageManager": "bun@1.3.12",
   "engines": {
     "bun": ">=1.0.0"
@@ -53,7 +58,7 @@
   },
   "dependencies": {
     "@package/logger-adapter": "npm:@trebired/logger-adapter@^0.4.9",
-    "@trebired/utils": "^0.4.4",
+    "@trebired/utils": "^0.4.5",
     "chart.js": "^4.5.1",
     "country-flag-icons": "^1.6.20",
     "cropperjs": "^1.6.2",