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

package/dist/src/lib/context/context.d.ts

@@ -1,284 +1,22 @@
-import { type Component, type ComponentChild } from '@fluixi/dom';
-import { Accessor, Context } from '@fluixi/reactive/signal';
-type C = Component | Component[];
-interface Children {
-    (): C;
-    (...args: any[]): C;
-}
-type PickChildren<T> = T extends Record<any, any> ? 'children' extends keyof T ? T['children'] : never : never;
-export interface ContextProvider<T, S> {
-    /**
-     * Context to provide
-     */
-    context: Context<T>;
-    /**
-     * Value to provide
-     */
-    value: T | Accessor<T>;
-    /**
-     * Children components that can access this context
-     */
-    debug?: boolean;
-    children?: (S extends Record<any, any> ? PickChildren<S> : never) | S;
-}
-export interface ProviderProps<Child> {
-    /**
-     * Children components that can access this context
-     */
-    children?: Child extends Record<any, any> ? PickChildren<Child> : never;
-}
 /**
- * Lazy-safe form: pass the component's `props` so `children` is read through a
- * getter (inside the stamped scope), never materialised early. This is the
- * recommended way to wrap an <Outlet/>.
+ * Context: a value provided by a component and read by any component below it.
  *
- *   function ThemeProvider(props) {
- *     return createProvider(ThemeContext, theme, props);
- *   }
- */
-export declare function createProvider<T>(context: Context<T>, value: T | Accessor<T>, props: {
-    children?: any;
-}): ComponentChild;
-/**
- * @deprecated Eager form: `{ context, value, children }` reads `children` before
- * the context is stamped (see warnEagerProvider). Use `createProvider(context,
- * value, props)` or `<Context.Provider>` instead.
- */
-/**
- * Provide a context value to a subtree, without writing the `Provider` tag.
- *
- * Takes either a `Context` from `createContext` or a provider component, so it works for
- * both shapes the context API hands back. `value` may be an accessor, in which case
- * descendants see it change.
- *
- * Reach for the `Provider` tag in markup; this is for providing a value from code, such as
- * a wrapper that supplies context around children it was handed.
- *
- * @example
- * ```ts
- * createProvider(ThemeContext, 'dark', { children: () => renderPage() });
- * ```
- */
-export declare function createProvider<T, S = Children>(props: ContextProvider<T, S>): ComponentChild;
-/**
- * Creates a context with a provider component
- *
- * Returns both the context and a convenience component that combines
- * context creation with the provider.
- *
- * @example
- * ```typescript
- * import { createContextWithProvider } from '@fluixi/core/context';
- * import { createSignal } from '@fluixi/reactive';
- * import { html } from 'lit';
- *
- * const [ThemeContext, ThemeProvider] = createContextWithProvider({
- *   primaryColor: '#007bff'
- * });
- *
- * 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>`;
- *   }
- * }
- * ```
- */
-export declare function createContextWithProvider<T, U>(defaultValue: T): [Context<T>, (props: Omit<ContextProvider<T, U>, 'context'>) => ComponentChild];
-/**
- * Creates multiple context providers in a nested structure
- *
- * Utility function to avoid deeply nested Provider components.
- *
- * @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>`
- *     );
- *   }
- * }
- * ```
- */
-export declare function composeProviders(contexts: Array<[Context<any>, any]>, children: Children): ComponentChild;
-/**
- * Creates a context consumer component
- *
- * Alternative to useContext hook, useful for rendering props patterns.
- *
- * @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>
- *         `
- *       })}
- *     `;
- *   }
- * }
- * ```
- */
-export declare function createConsumer<T>(context: Context<T>): (props: {
-    children: (value: T) => Component;
-}) => Component;
-/**
- * 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 declare function useProvide<T>(context: Context<T>, factory: () => T): T;
-/**
- * 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' });
- * ```
+ * 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.
  */
+import { type ComponentChild } from '@fluixi/dom';
+import { type Accessor, type Context } from '@fluixi/reactive/signal';
 /**
- * Create a context for sharing state across component tree
- *
- * Context is lookup-based, works on server and client
- * Supports nested contexts and complex values
+ * A context with a default for components that have no Provider above them. `name` is what
+ * devtools show for it.
  *
  * @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: () => {}
- * });
+ * ```tsx
+ * const Theme = createContext<'light' | 'dark'>('light', 'theme');
  *
- * // Usage in JSX
- * <ThemeContext.Provider value="dark">
- *   <Child />
- * </ThemeContext.Provider>
- *
- * // Usage in Lit-html
- * html`
- *   <${ThemeContext.Provider} value=${{ theme: 'dark', toggleTheme }}>
- *     <${Child} />
- *   </${ThemeContext.Provider}>
- * `
+ * <Theme.Provider value="dark"><Toolbar /></Theme.Provider>
  * ```
  */
 export declare function createContext<T>(defaultValue?: T, name?: string): {
@@ -290,30 +28,46 @@ export declare function createContext<T>(defaultValue?: T, name?: string): {
     }) => any;
     defaultValue: T;
 };
+/** The value of the nearest Provider above the calling component, or the context's default. */
+export declare function useContext<T>(context: {
+    id: symbol;
+    defaultValue: T;
+    [key: string]: any;
+}): T;
 /**
- * Use context value from nearest Provider
- *
- * Lookup-based, no subscriptions on server
+ * 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
- * const Child = () => {
- *   const theme = useContext(ThemeContext);
- *   const { theme: currentTheme, toggleTheme } = useContext(AppContext);
+ * ```ts
+ * const ThemeProvider = (props) => createProvider(Theme, 'dark', props);
+ * ```
+ */
+export declare function createProvider<T>(context: Context<T>, value: T | Accessor<T>, props: {
+    children?: any;
+}): ComponentChild;
+/**
+ * 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.
  *
- *   return html`
- *     <div>
- *       <p>Theme: ${currentTheme}</p>
- *       <button @click=${toggleTheme}>Toggle</button>
- *     </div>
- *   `;
- * };
+ * @example
+ * ```ts
+ * const AppProviders = (props) =>
+ *   composeProviders([[Theme, 'dark'], [Locale, () => locale()], [Session, session]], props);
  * ```
  */
-export declare function useContext<T>(context: {
+export declare function composeProviders(providers: ReadonlyArray<readonly [Context<any>, unknown]>, props: {
+    children?: any;
+}): ComponentChild;
+/**
+ * `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 declare function requireContext<T>(context: {
     id: symbol;
-    defaultValue: T;
+    defaultValue?: T;
     [key: string]: any;
-}): T;
+}, message?: string): T;
 export type { Context };
 //# sourceMappingURL=context.d.ts.map

package/dist/src/lib/context/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/lib/context/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/lib/context/context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,OAAO,EACb,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,GAAG,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,GAAG,CAAC;IACxE,YAAY,EAAE,CAAC,CAAC;CACjB,CAoBA;AAED,+FAA+F;AAC/F,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,CAAC,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GAAG,CAAC,CAG7F;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,EACtB,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,GAAG,CAAA;CAAE,GACxB,cAAc,CAQhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC,EAC1D,KAAK,EAAE;IAAE,QAAQ,CAAC,EAAE,GAAG,CAAA;CAAE,GACxB,cAAc,CAUhB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAKpH;AAED,YAAY,EAAE,OAAO,EAAE,CAAC"}