@fluixi/core 1.0.0-alpha.92 → 1.0.0-alpha.93

package/dist/src/lib/context/context.js

@@ -1,425 +1,93 @@
-// /**
-//  * @fileoverview Context API for Fluixi that wraps @fluixi/reactive context for Lit templates
-//  * @module @fluixi/core/context/context
-//  */
-import { asProvider } from '@fluixi/dom';
-import { createContext as createReactiveContext, useContext as useReactiveContext } from '@fluixi/reactive/signal';
-import { readChildren, } from '@fluixi/reactive/signal';
 /**
- * Provider component that supplies a context value to its descendants
- *
- * This wraps @fluixi/reactive's Provider for use with Lit templates.
- *
- * @example
- * ```typescript
- * import { createContext, Provider } from '@fluixi/core/context';
- * import { createSignal } from '@fluixi/reactive';
- * import { html } from 'lit';
+ * Context: a value provided by a component and read by any component below it.
  *
- * const ThemeContext = createContext({ primaryColor: '#007bff' });
- *
- * class App extends FluixiElement {
- *   private [theme, setTheme] = createSignal({ primaryColor: '#28a745' });
- *
- *   view() {
- *     return html`
- *       ${Provider({
- *         context: ThemeContext,
- *         value: this.theme(),
- *         children: html`
- *           <div>
- *             <themed-button></themed-button>
- *             <themed-text></themed-text>
- *           </div>
- *         `
- *       })}
- *     `;
- *   }
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Nested providers
- * const UserContext = createContext<User | null>(null);
- * const PermissionsContext = createContext<string[]>([]);
- *
- * class App extends FluixiElement {
- *   private [user, setUser] = createSignal<User | null>(null);
- *   private [permissions, setPermissions] = createSignal<string[]>(['read']);
- *
- *   view() {
- *     return html`
- *       ${Provider({
- *         context: UserContext,
- *         value: this.user(),
- *         children: Provider({
- *           context: PermissionsContext,
- *           value: this.permissions(),
- *           children: html`<app-dashboard></app-dashboard>`
- *         })
- *       })}
- *     `;
- *   }
- * }
- * ```
+ * The owner tree holds it (`@fluixi/reactive`), so `useContext` finds the nearest
+ * `<Ctx.Provider>` above the component that asks. The same object is the key custom elements use
+ * with `@fluixi/web-components`: an element reads what a Provider around it gives, and the
+ * components an element renders read what the element provides.
  */
-let _warnedEagerProvider = false;
-function warnEagerProvider() {
-    if (_warnedEagerProvider)
-        return;
-    _warnedEagerProvider = true;
-    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production')
-        return;
-    console.warn('[fluixi] createProvider({ context, value, children }) reads `children` eagerly: ' +
-        'the object literal materialises `children` BEFORE the context is stamped, so a ' +
-        'routed <Outlet/> that has siblings inside the provider renders detached and its ' +
-        'descendants see no context under SSR. Use the lazy form instead:\n' +
-        '  createProvider(Context, value, props)   // children stays a getter\n' +
-        '  // or JSX:  <Context.Provider value={...}>{props.children}</Context.Provider>');
-}
-// Returns the Provider's rendered output, not a component, it was annotated
-// `Component<T>`, which made `<MyProvider>` fail as a JSX element.
-export function createProvider(a, value, childProps) {
-    // Distinguish the two overloads: a Context (from createContext) exposes `.Provider`,
-    // whereas the deprecated form's first arg is the props object (which has `.context`).
-    const isLazyForm = !!a?.Provider;
-    const context = (isLazyForm ? a : a.context);
-    const rawValue = isLazyForm ? value : a.value;
-    const debug = isLazyForm ? false : (a.debug ?? false);
-    if (!isLazyForm)
-        warnEagerProvider();
-    // Resolve value if it's an accessor
-    const resolvedValue = typeof rawValue === 'function' ? rawValue() : rawValue;
-    // Always read children through a getter so they render INSIDE the stamped scope.
-    // For the lazy form `childProps.children` is still a getter here (untouched); for
-    // the eager form the caller already materialised it, so this can only mitigate,
-    // not fully fix: hence the deprecation warning above.
-    const sourceProps = isLazyForm ? childProps : a;
-    return context.Provider({
-        value: resolvedValue,
-        get children() { return sourceProps?.children; },
-        debug,
-    });
-    // // Wrap children in the reactive provider
-    // return html`${ReactiveProvider({
-    //   value: resolvedValue,
-    //   children: resolveChildren(children),
-    //   //<!--Array.isArray(children) ? html`${children}` : children,-->
-    // } as any)}`;
-}
+import { asProvider } from '@fluixi/dom';
+import { createContext as createReactiveContext, getOwner, useContext as useReactiveContext, } from '@fluixi/reactive/signal';
 /**
- * Creates a context with a provider component
- *
- * Returns both the context and a convenience component that combines
- * context creation with the provider.
+ * A context with a default for components that have no Provider above them. `name` is what
+ * devtools show for it.
  *
  * @example
- * ```typescript
- * import { createContextWithProvider } from '@fluixi/core/context';
- * import { createSignal } from '@fluixi/reactive';
- * import { html } from 'lit';
- *
- * const [ThemeContext, ThemeProvider] = createContextWithProvider({
- *   primaryColor: '#007bff'
- * });
+ * ```tsx
+ * const Theme = createContext<'light' | 'dark'>('light', 'theme');
  *
- * class App extends FluixiElement {
- *   private [theme] = createSignal({ primaryColor: '#28a745' });
- *
- *   view() {
- *     return html`
- *       ${ThemeProvider({
- *         value: this.theme(),
- *         children: html`<div><themed-button></themed-button></div>`
- *       })}
- *     `;
- *   }
- * }
- *
- * class ThemedButton extends FluixiElement {
- *   view() {
- *     const theme = useContext(ThemeContext);
- *     return html`<button style="color: ${theme.primaryColor}">Click</button>`;
- *   }
- * }
+ * <Theme.Provider value="dark"><Toolbar /></Theme.Provider>
  * ```
  */
-export function createContextWithProvider(defaultValue) {
-    const context = createContext(defaultValue);
-    const provider = (props) => {
-        // Lazy-safe form so children (which may contain an <Outlet/>) render inside
-        // the stamped scope.
-        return createProvider(context, props.value, props);
+export function createContext(defaultValue, name) {
+    const context = createReactiveContext(defaultValue, name);
+    const Provider = (props) => 
+    // Children stay a getter: the reactive Provider reads them after stamping the value on
+    // its owner. Reading `props.children` here would render them, and any <Outlet/> in them,
+    // before the context exists.
+    context.Provider({
+        value: props.value,
+        get children() {
+            return props.children;
+        },
+        debug: props.debug,
+    });
+    return {
+        id: context.id,
+        Provider: asProvider(Provider),
+        defaultValue: defaultValue,
     };
-    return [context, provider];
+}
+/** The value of the nearest Provider above the calling component, or the context's default. */
+export function useContext(context) {
+    const value = useReactiveContext(context);
+    return value !== undefined ? value : context.defaultValue;
 }
 /**
- * Creates multiple context providers in a nested structure
- *
- * Utility function to avoid deeply nested Provider components.
+ * A Provider as a function call, for a component that provides without JSX. `value` may be an
+ * accessor, read once. Pass the component's own props so `children` stays lazy.
  *
  * @example
- * ```typescript
- * import { composeProviders, createContext } from '@fluixi/core/context';
- * import { createSignal } from '@fluixi/reactive';
- * import { html } from 'lit';
- *
- * const ThemeContext = createContext({ dark: false });
- * const UserContext = createContext<User | null>(null);
- * const LocaleContext = createContext('en');
- *
- * class App extends FluixiElement {
- *   private [theme] = createSignal({ dark: true });
- *   private [user] = createSignal<User | null>({ id: 1, name: 'Alice' });
- *   private [locale] = createSignal('fr');
- *
- *   view() {
- *     return composeProviders(
- *       [
- *         [ThemeContext, this.theme()],
- *         [UserContext, this.user()],
- *         [LocaleContext, this.locale()]
- *       ],
- *       html`<app-dashboard></app-dashboard>`
- *     );
- *   }
- * }
+ * ```ts
+ * const ThemeProvider = (props) => createProvider(Theme, 'dark', props);
  * ```
  */
-export function composeProviders(contexts, children) {
-    if (contexts.length === 0) {
-        return readChildren(() => children);
-    }
-    const [context, value] = contexts[0];
-    const remaining = contexts.slice(1);
-    // Lazy-safe form: defer the nested children behind a getter so each provider
-    // stamps its context before the inner providers/children render.
-    return createProvider(context, value, {
-        get children() { return composeProviders(remaining, children); },
+export function createProvider(context, value, props) {
+    const resolved = typeof value === 'function' ? value() : value;
+    return context.Provider({
+        value: resolved,
+        get children() {
+            return props.children;
+        },
     });
 }
 /**
- * Creates a context consumer component
- *
- * Alternative to useContext hook, useful for rendering props patterns.
+ * Several Providers as one, outermost first, for an app shell that would otherwise nest a
+ * Provider per context. Values may be accessors, as in `createProvider`; children stay lazy.
  *
  * @example
- * ```typescript
- * import { createContext, createConsumer } from '@fluixi/core/context';
- * import { html } from 'lit';
- *
- * const ThemeContext = createContext({ primaryColor: '#007bff' });
- * const ThemeConsumer = createConsumer(ThemeContext);
- *
- * class MyComponent extends FluixiElement {
- *   view() {
- *     return html`
- *       ${ThemeConsumer({
- *         children: (theme) => html`
- *           <div style="color: ${theme.primaryColor}">
- *             Themed content
- *           </div>
- *         `
- *       })}
- *     `;
- *   }
- * }
+ * ```ts
+ * const AppProviders = (props) =>
+ *   composeProviders([[Theme, 'dark'], [Locale, () => locale()], [Session, session]], props);
  * ```
  */
-export function createConsumer(context) {
-    return (props) => {
-        const value = useContext(context);
-        return props.children(value);
-    };
+export function composeProviders(providers, props) {
+    const outermost = providers.reduceRight((inner, [context, value]) => ({
+        get children() {
+            return createProvider(context, value, inner);
+        },
+    }), props);
+    return outermost.children;
 }
 /**
- * Hook to provide and consume a context in one component
- *
- * Useful for creating context-based stores or services.
- *
- * @example
- * ```typescript
- * import { createContext, useProvide, Provider } from '@fluixi/core/context';
- * import { createSignal } from '@fluixi/reactive';
- * import { html } from 'lit';
- *
- * interface Counter {
- *   count: number;
- *   increment: () => void;
- * }
- *
- * const CounterContext = createContext<Counter>({
- *   count: 0,
- *   increment: () => {}
- * });
- *
- * class CounterProvider extends FluixiElement {
- *   view() {
- *     const counter = useProvide(CounterContext, () => {
- *       const [count, setCount] = createSignal(0);
- *       return {
- *         count: count(),
- *         increment: () => setCount(count() + 1)
- *       };
- *     });
- *
- *     return html`
- *       ${Provider({
- *         context: CounterContext,
- *         value: counter,
- *         children: html`<slot></slot>`
- *       })}
- *     `;
- *   }
- * }
- * ```
- */
-export function useProvide(context, factory) {
-    // Check if already provided
-    const existing = useContext(context);
-    // If we got the default value, create new instance
-    if (existing === context.defaultValue) {
-        return factory();
-    }
-    return existing;
-}
-/**
- * Creates a scoped context that only exists within a specific component tree
- *
- * @example
- * ```typescript
- * import { createContext } from '@fluixi/core/context';
- *
- * // This context won't leak to parent or sibling components
- * const LocalContext = createContext({ data: 'local' });
- * ```
- */
-// export function createContext<T>(defaultValue: T): Context<T> {
-//   // Create a unique symbol-based context for scoping
-//   return createContext(defaultValue);
-// }
-//
-//
-// ============================================================================
-// CONTEXT HELPERS
-// ============================================================================
-/**
- * Create a context for sharing state across component tree
- *
- * Context is lookup-based, works on server and client
- * Supports nested contexts and complex values
- *
- * @example
- * ```typescript
- * // Simple context
- * const ThemeContext = createContext('light');
- *
- * // Complex context with object
- * const AppContext = createContext({
- *   theme: 'light',
- *   toggleTheme: () => {}
- * });
- *
- * // Usage in JSX
- * <ThemeContext.Provider value="dark">
- *   <Child />
- * </ThemeContext.Provider>
- *
- * // Usage in Lit-html
- * html`
- *   <${ThemeContext.Provider} value=${{ theme: 'dark', toggleTheme }}>
- *     <${Child} />
- *   </${ThemeContext.Provider}>
- * `
- * ```
- */
-/**
- * Creates a scoped context that only exists within a specific component tree
- *
- * @example
- * ```typescript
- * import { createContext } from '@fluixi/core';
- *
- * // This context won't leak to parent or sibling components
- * const LocalContext = createContext({ data: 'local' });
- * ```
- * @example
- * ```typescript
- * // Simple context
- * const ThemeContext = createContext('light');
- *
- * // Complex context with object
- * const AppContext = createContext({
- *   theme: 'light',
- *   toggleTheme: () => {}
- * });
- *
- * // Usage in JSX
- * <ThemeContext.Provider value="dark">
- *   <Child />
- * </ThemeContext.Provider>
- *
- * // Usage in Lit-html
- * html`
- *   <${ThemeContext.Provider} value=${{ theme: 'dark', toggleTheme }}>
- *     <${Child} />
- *   </${ThemeContext.Provider}>
- * `
- * ```
+ * `useContext` for a value that has to come from a Provider: throws when none is above,
+ * instead of handing back the default. For parts that only work inside their parent, a tab
+ * outside its tabs.
  */
-export function createContext(defaultValue, name) {
-    const context = createReactiveContext(defaultValue, name);
-    // Wrap Provider to work with both JSX and Lit-html
-    const Provider = (props) => {
-        if (props.debug === true) {
-        }
-        // Pass children LAZILY (a getter). The reactive Provider reads children inside
-        // its render effect, after stamping the context on the owner. Reading
-        // props.children here (e.g. `children: props.children`) evaluates the imperative
-        // `get children()` getter eagerly, so the children, and any <Outlet/> in them,
-        // render before the context is available.
-        return context.Provider({
-            value: props.value,
-            get children() {
-                return props.children;
-            },
-            debug: props.debug,
-        });
-    };
-    // For JSX: Provider.$$typeof support
-    if (typeof Symbol !== 'undefined' && Symbol.for) {
-        Provider.$$typeof = Symbol.for('react.provider');
+export function requireContext(context, message) {
+    for (let owner = getOwner(); owner; owner = owner.parent) {
+        if (owner.contexts?.has(context.id))
+            return useContext(context);
     }
-    Provider.$$typeof = Symbol.for('react.provider');
-    return {
-        id: context.id,
-        Provider: asProvider(Provider),
-        defaultValue: defaultValue,
-    };
-}
-/**
- * Use context value from nearest Provider
- *
- * Lookup-based, no subscriptions on server
- *
- * @example
- * ```typescript
- * const Child = () => {
- *   const theme = useContext(ThemeContext);
- *   const { theme: currentTheme, toggleTheme } = useContext(AppContext);
- *
- *   return html`
- *     <div>
- *       <p>Theme: ${currentTheme}</p>
- *       <button @click=${toggleTheme}>Toggle</button>
- *     </div>
- *   `;
- * };
- * ```
- */
-export function useContext(context) {
-    // Use reactive context lookup: walks up Owner chain
-    const value = useReactiveContext(context);
-    return value !== undefined ? value : context.defaultValue;
+    throw new Error(message ?? `[fluixi] No Provider for ${context.id.description ?? 'this context'} above this component.`);
 }

package/dist/src/lib/context/context.mjs

@@ -1,83 +1,24 @@
 // src/lib/context/context.ts
 import { asProvider } from "@fluixi/dom";
-import { createContext as createReactiveContext, useContext as useReactiveContext } from "@fluixi/reactive/signal";
 import {
-  readChildren
+  createContext as createReactiveContext,
+  getOwner,
+  useContext as useReactiveContext
 } from "@fluixi/reactive/signal";
-var _warnedEagerProvider = false;
-function warnEagerProvider() {
-  if (_warnedEagerProvider) return;
-  _warnedEagerProvider = true;
-  if (typeof process !== "undefined" && true) return;
-  console.warn(
-    "[fluixi] createProvider({ context, value, children }) reads `children` eagerly: the object literal materialises `children` BEFORE the context is stamped, so a routed <Outlet/> that has siblings inside the provider renders detached and its descendants see no context under SSR. Use the lazy form instead:\n  createProvider(Context, value, props)   // children stays a getter\n  // or JSX:  <Context.Provider value={...}>{props.children}</Context.Provider>"
-  );
-}
-function createProvider(a, value, childProps) {
-  const isLazyForm = !!a?.Provider;
-  const context = isLazyForm ? a : a.context;
-  const rawValue = isLazyForm ? value : a.value;
-  const debug = isLazyForm ? false : a.debug ?? false;
-  if (!isLazyForm) warnEagerProvider();
-  const resolvedValue = typeof rawValue === "function" ? rawValue() : rawValue;
-  const sourceProps = isLazyForm ? childProps : a;
-  return context.Provider({
-    value: resolvedValue,
-    get children() {
-      return sourceProps?.children;
-    },
-    debug
-  });
-}
-function createContextWithProvider(defaultValue) {
-  const context = createContext(defaultValue);
-  const provider = (props) => {
-    return createProvider(context, props.value, props);
-  };
-  return [context, provider];
-}
-function composeProviders(contexts, children) {
-  if (contexts.length === 0) {
-    return readChildren(() => children);
-  }
-  const [context, value] = contexts[0];
-  const remaining = contexts.slice(1);
-  return createProvider(context, value, {
-    get children() {
-      return composeProviders(remaining, children);
-    }
-  });
-}
-function createConsumer(context) {
-  return (props) => {
-    const value = useContext(context);
-    return props.children(value);
-  };
-}
-function useProvide(context, factory) {
-  const existing = useContext(context);
-  if (existing === context.defaultValue) {
-    return factory();
-  }
-  return existing;
-}
 function createContext(defaultValue, name) {
   const context = createReactiveContext(defaultValue, name);
-  const Provider = (props) => {
-    if (props.debug === true) {
-    }
-    return context.Provider({
+  const Provider = (props) => (
+    // Children stay a getter: the reactive Provider reads them after stamping the value on
+    // its owner. Reading `props.children` here would render them, and any <Outlet/> in them,
+    // before the context exists.
+    context.Provider({
       value: props.value,
       get children() {
         return props.children;
       },
       debug: props.debug
-    });
-  };
-  if (typeof Symbol !== "undefined" && Symbol.for) {
-    Provider.$$typeof = /* @__PURE__ */ Symbol.for("react.provider");
-  }
-  Provider.$$typeof = /* @__PURE__ */ Symbol.for("react.provider");
+    })
+  );
   return {
     id: context.id,
     Provider: asProvider(Provider),
@@ -88,12 +29,36 @@ function useContext(context) {
   const value = useReactiveContext(context);
   return value !== void 0 ? value : context.defaultValue;
 }
+function createProvider(context, value, props) {
+  const resolved = typeof value === "function" ? value() : value;
+  return context.Provider({
+    value: resolved,
+    get children() {
+      return props.children;
+    }
+  });
+}
+function composeProviders(providers, props) {
+  const outermost = providers.reduceRight(
+    (inner, [context, value]) => ({
+      get children() {
+        return createProvider(context, value, inner);
+      }
+    }),
+    props
+  );
+  return outermost.children;
+}
+function requireContext(context, message) {
+  for (let owner = getOwner(); owner; owner = owner.parent) {
+    if (owner.contexts?.has(context.id)) return useContext(context);
+  }
+  throw new Error(message ?? `[fluixi] No Provider for ${context.id.description ?? "this context"} above this component.`);
+}
 export {
   composeProviders,
-  createConsumer,
   createContext,
-  createContextWithProvider,
   createProvider,
-  useContext,
-  useProvide
+  requireContext,
+  useContext
 };