@_linked/cli 1.4.2 → 1.4.4

package/defaults/app-with-backend/src/layout/Header.module.css

@@ -0,0 +1,46 @@
+@import '@_linked/css/package.css';
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: --spacing(4);
+  padding: --spacing(4) 0 --spacing(6);
+  flex-wrap: wrap;
+}
+
+.header h1 {
+  color: var(--color-primary-700);
+  margin: 0;
+}
+
+.menu {
+  display: flex;
+  gap: --spacing(1);
+  flex-wrap: wrap;
+}
+
+.menu > a {
+  font-weight: 500;
+  font-size: 0.95rem;
+  color: var(--color-gray-700);
+  padding: --spacing(2) --spacing(3);
+  border-radius: var(--radius-element);
+  text-decoration: none;
+  transition: background 120ms ease, color 120ms ease;
+}
+
+.menu > a:hover {
+  background: var(--color-gray-100);
+  color: var(--color-gray-900);
+}
+
+.menu > a.active {
+  background: var(--color-primary-500);
+  color: var(--color-white);
+}
+
+.menu > a.active:hover {
+  background: var(--color-primary-600);
+  color: var(--color-white);
+}

package/defaults/app-with-backend/src/layout/Header.tsx

@@ -0,0 +1,27 @@
+import { Link, useLocation } from 'react-router-dom';
+import React from 'react';
+import style from './Header.module.css';
+import { ROUTES } from '../routes';
+
+export function Header() {
+  let path = useLocation();
+  return (
+    <header className={style.header}>
+      <h1>${name}</h1>
+      <nav className={style.menu}>
+        {Object.keys(ROUTES).map((key) => {
+          if (ROUTES[key].excludeFromMenu) return null;
+          return (
+            <Link
+              key={key}
+              to={ROUTES[key].path}
+              className={ROUTES[key].path === path.pathname ? style.active : ''}
+            >
+              {ROUTES[key].label || key}
+            </Link>
+          );
+        })}
+      </nav>
+    </header>
+  );
+}

package/defaults/app-with-backend/src/linked.frontend.datasets.json

@@ -0,0 +1,12 @@
+{
+  "_note": "Frontend datasets config. Public values only — this file ships in the browser bundle. Each entry: `store` (npm import path to the IDataset class) + `config` (a single JSON object passed verbatim to `new StoreClass(config)`). The default BackendAPIStore entry proxies queries to this app's own backend; swap in a different store class (e.g. @_linked/fuseki/shapes/FusekiStore) to talk directly to a public SPARQL endpoint.",
+
+  "datasets": {
+    "appData": {
+      "store": "@_linked/server/shapes/quadstores/BackendAPIStore",
+      "config": {
+        "name": "appData"
+      }
+    }
+  }
+}

package/defaults/app-with-backend/src/linked.frontend.storage.ts

@@ -0,0 +1,36 @@
+// Frontend storage for ${name}.
+//
+// Reads linked.frontend.datasets.json and instantiates one store per
+// alias. Webpack can't bundle dynamic imports of arbitrary npm paths,
+// so on the frontend we import each store class explicitly and
+// construct it per-alias here.
+//
+// Aliases on this side are independent from backend aliases — the
+// framework re-routes by shape on each side.
+import datasetsConfig from './linked.frontend.datasets.json' assert { type: 'json' };
+import { parseDatasetsConfig } from '@_linked/core/utils/parseDatasetsConfig';
+import { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';
+import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
+import { BackendAPIStore } from '@_linked/server/shapes/quadstores/BackendAPIStore';
+import { getAccessUrlLocalFileStore } from '@_linked/server/utils/accessUrl';
+// Direct-to-Fuseki on the frontend? Uncomment:
+// import { FusekiStore } from '@_linked/fuseki/shapes/FusekiStore';
+
+// Parse JSON; pass empty env since the browser has no runtime process.env.
+// Per-env values for the frontend should be hardcoded `process.env.X`
+// references (webpack inlines them at build time).
+const config = parseDatasetsConfig(datasetsConfig, {});
+
+// One store per alias. Each line imports the class above and constructs it
+// with the alias's `config`. Adding a new alias = add an import + a line.
+const appData = new BackendAPIStore(config.datasets.appData.config);
+// Direct-to-Fuseki alternative (no creds in browser):
+// const appData = new FusekiStore(config.datasets.appData.config);
+
+// Shape → alias. For multi-alias setups add per-shape pins, e.g.:
+//   import { PageView } from './shapes/PageView';
+//   LinkedStorage.setDatasetForShapes(analytics, [PageView]);
+LinkedStorage.setDefaultDataset(appData);
+
+// File asset URLs.
+LinkedFileStorage.setDefaultAccessURL(getAccessUrlLocalFileStore());

package/defaults/app-with-backend/src/package.ts

@@ -0,0 +1,12 @@
+import { linkedPackage } from '@_linked/core/utils/Package';
+
+export const {
+  linkedComponent,
+  linkedSetComponent,
+  linkedShape,
+  linkedUtil,
+  linkedOntology,
+  registerPackageExport,
+  packageExports,
+  packageName,
+} = linkedPackage('${hyphen_name}');

package/defaults/app-with-backend/src/pages/Home.module.css

@@ -0,0 +1,23 @@
+@import '@_linked/css/package.css';
+
+.Home {
+  display: block;
+  margin: --spacing(4) 0;
+}
+
+.Home code {
+  font-family: var(--font-mono);
+  background: var(--bg-section);
+  padding: 0 --spacing(1);
+  border-radius: var(--radius-element);
+  font-size: 0.85em;
+}
+
+.Home pre {
+  padding: --spacing(4);
+  background: var(--bg-section);
+  border-radius: var(--radius-element);
+  overflow-x: auto;
+  font-family: var(--font-mono);
+  margin: --spacing(2) 0;
+}

package/defaults/app-with-backend/src/pages/Home.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { DefaultLayout } from '../layout/DefaultLayout';
+import { PersonOverview } from '../components/PersonOverview';
+import style from './Home.module.css';
+
+export default function Home() {
+  return (
+    <DefaultLayout>
+      <div className={style.Home}>
+        <PersonOverview />
+      </div>
+    </DefaultLayout>
+  );
+}

package/defaults/app-with-backend/src/pages/Page1.module.css

@@ -0,0 +1,18 @@
+@import '@_linked/css/package.css';
+
+.Card {
+  background: var(--bg-card);
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-card);
+  padding: --spacing(6);
+}
+
+.Card h2 {
+  margin: 0 0 --spacing(3);
+}
+
+.Card p {
+  color: var(--color-gray-700);
+  line-height: 1.5;
+  margin: 0;
+}

package/defaults/app-with-backend/src/pages/Page1.tsx

@@ -0,0 +1,16 @@
+import { DefaultLayout } from '../layout/DefaultLayout';
+import style from './Page1.module.css';
+
+export default function Page1() {
+  return (
+    <DefaultLayout>
+      <div className={style.Card}>
+        <h2>Page 1</h2>
+        <p>
+          A second route to show how navigation works. Edit{' '}
+          <code>src/pages/Page1.tsx</code> to make this your own.
+        </p>
+      </div>
+    </DefaultLayout>
+  );
+}

package/defaults/app-with-backend/src/pages/PageNotFound.module.css

@@ -0,0 +1,19 @@
+@import '@_linked/css/package.css';
+
+.Card {
+  background: var(--bg-card);
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-card);
+  padding: --spacing(6);
+  text-align: center;
+}
+
+.Card h2 {
+  margin: 0 0 --spacing(3);
+}
+
+.Card p {
+  color: var(--color-gray-700);
+  line-height: 1.5;
+  margin: 0;
+}

package/defaults/app-with-backend/src/pages/PageNotFound.tsx

@@ -0,0 +1,14 @@
+import React from 'react';
+import { DefaultLayout } from '../layout/DefaultLayout';
+import style from './PageNotFound.module.css';
+
+export default function PageNotFound() {
+  return (
+    <DefaultLayout>
+      <div className={style.Card}>
+        <h2>Page not found</h2>
+        <p>The page you were looking for does not exist.</p>
+      </div>
+    </DefaultLayout>
+  );
+}

package/defaults/app-with-backend/src/pages/Signin.module.css

@@ -0,0 +1,20 @@
+@import '@_linked/css/package.css';
+
+.Card {
+  background: var(--bg-card);
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-card);
+  padding: --spacing(6);
+  max-width: 480px;
+  margin: --spacing(8) auto;
+}
+
+.Card h2 {
+  margin: 0 0 --spacing(3);
+}
+
+.Card p {
+  color: var(--color-gray-700);
+  line-height: 1.5;
+  margin: 0;
+}

package/defaults/app-with-backend/src/pages/Signin.tsx

@@ -0,0 +1,16 @@
+import { DefaultLayout } from '../layout/DefaultLayout';
+import style from './Signin.module.css';
+
+export default function Signin() {
+  return (
+    <DefaultLayout>
+      <div className={style.Card}>
+        <h2>Sign in</h2>
+        <p>
+          See <a href="https://linked.cm">linked.cm</a> for different ways to
+          sign in.
+        </p>
+      </div>
+    </DefaultLayout>
+  );
+}

package/defaults/app-with-backend/src/routes.tsx

@@ -0,0 +1,85 @@
+import { RequireAuth } from '@_linked/auth/components/RequireAuth';
+import type { RoutesConfig } from '@_linked/server/types/RouteConfig';
+import React, { lazy, Suspense } from 'react';
+import { Route, Routes } from 'react-router-dom';
+import { Spinner } from './components/Spinner';
+import PageNotFound from './pages/PageNotFound';
+import { lazyWithPreload } from './utils/lazyWithPreload';
+
+// Create preloadable lazy components for direct-entry routes
+const HomePage = lazyWithPreload(
+  () => import(/* webpackChunkName: "home" */ './pages/Home')
+);
+
+const SigninPage = lazyWithPreload(
+  () => import(/* webpackChunkName: "signin" */ './pages/Signin')
+);
+
+// Export preloadable components for server-side preloading
+export const PRELOADABLE_ROUTES = {
+  home: HomePage,
+  signin: SigninPage,
+};
+
+
+export const ROUTES: RoutesConfig = {
+  home: {
+    path: '/',
+    component: HomePage.Component,
+    label: 'Home',
+    preloadChunks: ['home'],
+  },
+  page1: {
+    path: '/page1',
+    component: lazy(
+      () => import(/* webpackChunkName: "page1" */ './pages/Page1')
+    ),
+    label: 'Protected page',
+    requireAuth: true,
+    preloadChunks: ['page1'],
+  },
+  signin: {
+    path: '/signin',
+    component: SigninPage.Component,
+    label: 'Sign In',
+    excludeFromMenu: true,
+    preloadChunks: ['signin'],
+  },
+};
+
+export default function AppRoutes() {
+  return (
+    <Routes>
+      {Object.keys(ROUTES).map((routeName) => {
+        const route = ROUTES[routeName];
+        const Component = route.component;
+
+        //if a route is marked as requireAuth, wrap it in the RequireAuth component and pass the signinRoute
+        const AuthGuard = route.requireAuth ? RequireAuth : React.Fragment;
+        const authProps = route.requireAuth
+          ? { signinRoute: ROUTES.signin.path }
+          : {};
+
+        // define a render function that determines what to render based on the component and route.render
+        const renderRoute = () =>
+          // if a Component is defined, render it using JSX syntax (<Component />)
+          // if not, check if a route.render function is defined and call that render function if available.
+          // if neither Component nor route.render is defined, return null
+          Component ? <Component /> : route.render ? route.render() : null;
+
+        return (
+          <Route
+            key={route.path}
+            path={route.path}
+            element={
+              <AuthGuard {...authProps}>
+                <Suspense fallback={<Spinner />}>{renderRoute()}</Suspense>
+              </AuthGuard>
+            }
+          />
+        );
+      })}
+      <Route path="*" element={<PageNotFound />} />
+    </Routes>
+  );
+}

package/defaults/app-with-backend/src/theme.css

@@ -0,0 +1,91 @@
+/*
+ * Theme overrides for ${name}.
+ *
+ * The default palette below is a teal-blue primary + mint-green secondary.
+ * Override --color-primary-* / --color-secondary-* to your own brand.
+ *
+ * Available tokens (palette, surfaces, shadows, radii, spacing) are documented in:
+ *   https://github.com/linked-cm/css/blob/main/README.md
+ *   https://github.com/linked-cm/css/blob/main/docs/styling-and-themes.md
+ */
+
+/* Tailwind v4 layers — split-import pattern to substitute the Linked preflight.
+   See @_linked/css README "Why the split-import?" for details. */
+@layer theme, base, components, utilities;
+@import 'tailwindcss/theme.css' layer(theme);
+@import '@_linked/css/preflight.css';
+@import 'tailwindcss/utilities.css' layer(utilities);
+
+/* Apply Tailwind config from @_linked/cli — ensures all @_linked/* shapes
+   are scanned for utility classes. */
+@config "@_linked/cli/tailwind.config.js";
+
+/* @_linked/css: framework theme defaults + utility mixins.
+   App-specific @theme overrides below extend / replace these defaults. */
+@import '@_linked/css/theme-defaults.css';
+@import '@_linked/css/utilities.css';
+
+@theme {
+    /* === Primary palette — Linked teal-blue === */
+    --color-primary-50:  #f7fbfd;
+    --color-primary-100: #eef7fb;
+    --color-primary-200: #d3ebf5;
+    --color-primary-300: #a8d7ec;
+    --color-primary-400: #71bbdd;
+    --color-primary-500: #116d8d; /* base */
+    --color-primary-600: #0a5f7d;
+    --color-primary-700: #005970;
+    --color-primary-800: #004d61;
+    --color-primary-900: #001f28;
+
+    /* === Secondary palette — mint green === */
+    --color-secondary-50:  #f9fdfc;
+    --color-secondary-100: #f4fbf8;
+    --color-secondary-200: #e6f5ef;
+    --color-secondary-300: #ccebe0;
+    --color-secondary-400: #b1e0cd;
+    --color-secondary-500: #52a181; /* base */
+    --color-secondary-600: #297a5c;
+    --color-secondary-700: #146b4f;
+    --color-secondary-800: #005d43;
+    --color-secondary-900: #00201a;
+
+    /* === Shadows === */
+    --shadow-surface: var(--shadow-sm);  /* Background panels, sections */
+    --shadow-card: var(--shadow-md);     /* Cards, organized content blocks */
+    --shadow-popover: var(--shadow-lg);  /* Tooltips, dropdowns, popovers */
+    --shadow-modal: var(--shadow-2xl);   /* Modals, overlays */
+    --shadow-floating-action: var(--shadow-lg);
+    --shadow-content: none;              /* Buttons, inputs inside surfaces */
+
+    /* === Backgrounds / Surfaces === */
+    --bg-page: var(--color-gray-50);
+    --bg-section: var(--color-gray-100);
+    --bg-card: var(--color-white);
+    --bg-popover: var(--color-white);
+    --bg-modal: var(--color-white);
+    --bg-sidebar: var(--color-gray-200);
+    --bg-footer: var(--color-gray-300);
+    --bg-overlay: var(--color-gray-900);
+    --color-card: var(--color-white);
+
+    /* === Border radius === */
+    --radius-surface: var(--radius-sm);
+    --radius-card: var(--radius-lg);
+    --radius-element: var(--radius-md);
+    --radius-popover: var(--radius-md);
+    --radius-modal: var(--radius-2xl);
+    --radius-floating-action: var(--radius-full);
+    --radius-none: 0px;
+
+    /* === Z-index === */
+    --z-base: 0;
+    --z-surface: 10;
+    --z-popover: 30;
+    --z-modal: 50;
+    --z-overlay: 75;
+    --z-tooltip: 100;
+
+    /* === Spacing tokens === */
+    --spacing-card: calc(var(--spacing) * 4);
+}

package/defaults/app-with-backend/src/types.ts

@@ -0,0 +1,14 @@
+declare module '*.css' {
+  const styles: {
+    readonly [key: string]: string;
+  };
+  // export type ClassName = string;
+  export default styles;
+}
+declare module '*.scss' {
+  const styles: {
+    readonly [key: string]: string;
+  };
+  // export type ClassName = string;
+  export default styles;
+}

package/defaults/app-with-backend/src/utils/lazyWithPreload.tsx

@@ -0,0 +1,42 @@
+import { ComponentType, lazy } from 'react';
+
+export interface PreloadableComponent<T extends ComponentType<any>> {
+  preload: () => Promise<{ default: T }>;
+  Component: React.LazyExoticComponent<T>;
+}
+
+/**
+ * Creates a lazy-loaded component with a preload function
+ * This allows preloading the component before React needs it
+ *
+ * @example
+ * const SigninPage = lazyWithPreload(() => import('./pages/Signin'));
+ * // Later, before navigation or on server:
+ * SigninPage.preload();
+ */
+export function lazyWithPreload<T extends ComponentType<any>>(
+  importFunc: () => Promise<{ default: T }>
+): PreloadableComponent<T> {
+  let modulePromise: Promise<{ default: T }> | null = null;
+
+  const preload = () => {
+    if (!modulePromise) {
+      modulePromise = importFunc();
+    }
+    return modulePromise;
+  };
+
+  const Component = lazy(() => {
+    // If preload was called, reuse the same promise
+    // This ensures React uses the already-loaded module
+    if (!modulePromise) {
+      modulePromise = importFunc();
+    }
+    return modulePromise;
+  });
+
+  return {
+    preload,
+    Component,
+  };
+}

package/defaults/app-with-backend/src/utils/preloadRoutes.ts

@@ -0,0 +1,38 @@
+/**
+ * Client-side script to preload lazy routes before hydration
+ * This should be called BEFORE React's hydrateRoot()
+ */
+
+// This will be populated by the server with the routes that need preloading
+declare global {
+  interface Window {
+    __PRELOAD_ROUTES__?: string[];
+  }
+}
+
+export async function preloadMatchedRoute() {
+  // Get the list of routes to preload from the server
+  const routesToPreload = window.__PRELOAD_ROUTES__ || [];
+
+  if (routesToPreload.length === 0) {
+    return;
+  }
+
+  // Dynamically import the routes module to access PRELOADABLE_ROUTES
+  const routesModule = await import('../routes');
+  const { PRELOADABLE_ROUTES } = routesModule;
+
+  // Preload each route
+  const preloadPromises = routesToPreload
+    .map((routeKey) => {
+      const preloadableRoute = PRELOADABLE_ROUTES[routeKey];
+      if (preloadableRoute && preloadableRoute.preload) {
+        return preloadableRoute.preload();
+      }
+      return null;
+    })
+    .filter(Boolean);
+
+  // Wait for all preloads to complete
+  await Promise.all(preloadPromises);
+}

package/defaults/app-with-backend/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "module": "esnext",
+    "moduleResolution": "node",
+    "sourceMap": true,
+    "target": "es2018",
+    "resolveJsonModule": true,
+    "declaration": false,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "jsx": "react-jsx",
+    "types": ["node", "react", "react-dom"],
+    "plugins": [
+      {
+        "name": "typescript-plugin-css-modules"
+      }
+    ],
+    "pretty": true
+  },
+  "files": ["./src/index.tsx", "./src/types.ts"],
+  "include": ["./src/backend.ts"]
+}

package/defaults/package/package.json

@@ -18,9 +18,11 @@
   "license": "ISC",
   "scripts": {
     "start": "yarn linked dev",
-    "build": "yarn linked build",
-    "prepublishOnly": "yarn linked build production",
-    "postpublish": "yarn linked register"
+    "build": "rimraf ./lib && yarn build-esm && yarn build-cjs && yarn copy-to-lib && yarn dual-package",
+    "build-esm": "echo \"compiling ESM\" && rimraf ./lib/esm && yarn tsc -p tsconfig-esm.json",
+    "build-cjs": "echo \"compiling CJS\" && rimraf ./lib/cjs && yarn tsc -p tsconfig-cjs.json",
+    "copy-to-lib": "echo 'copying CSS + JSON assets to lib folder' && yarn copyfiles -u 1 'src/**/*.css' 'src/**/*.json' lib/esm && yarn copyfiles -u 1 'src/**/*.css' 'src/**/*.json' lib/cjs",
+    "dual-package": "echo 'adding package.json to each lib folder for dual output support' && yarn tsconfig-to-dual-package ./tsconfig-cjs.json ./tsconfig-esm.json"
   },
   "keywords": [
     "linked",
@@ -58,6 +60,8 @@
   "devDependencies": {
     "@types/node": "^22.13.14",
     "@_linked/cli": "^1.2",
+    "copyfiles": "^2.4.1",
+    "rimraf": "^5.0.7",
     "tsconfig-to-dual-package": "^1.2.0",
     "typescript": "^5.7.3"
   }

package/lib/cjs/cli-deprecated.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env tsx
+//# sourceMappingURL=cli-deprecated.d.ts.map