@ag2/weave 0.12.0 → 0.14.0

package/README.md

@@ -4,6 +4,42 @@
 
 The AG2 Space design system. Forked from [folds](https://github.com/cinnyapp/folds) 2.6.2 (Apache-2.0); `@ag2/weave@0.1.0` is folds@2.6.2 under the new name.
 
+## Temporary sidebar collapse
+
+Keep `PageNav` mounted and call `useRoomNavAutoCollapse` once from the room layout:
+
+```tsx
+import { useRoomNavAutoCollapse } from "@ag2/weave";
+
+useRoomNavAutoCollapse(commonsOpen && !isMobile, roomId);
+```
+
+The hook collapses the sidebar before paint without writing `roomNavCollapsed`.
+Closing Commons or unmounting the layout releases the request and restores the saved
+preference. Manual controls still use `useRoomNavCollapsed()`; they toggle the effective
+state, save the user's choice, and override requests already active. Switching tabs in
+the same room preserves that choice. Closing and reopening Commons, or changing `roomId`,
+starts a fresh automatic collapse. Leave the optional scope unchanged for the lifetime
+of one open panel, and disable the request on mobile.
+
+`useRoomNavCollapsed()` retains its existing tuple and animation options. The collapsed
+sidebar's restore button remains the way to expand it; no room-header control is needed.
+
+## Ambient orb background
+
+`OrbBackground` renders the Absorb / Calm / Aura field and is the default background
+of `SplashScreen`. Place it inside an element with the exported `OrbBackgroundHost`
+class so its decorative canvas sits behind content and is clipped at the surface edge.
+The parent supplies its background colour through the normal theme tokens.
+
+It follows the resolved `color.Background.Container` token, including nested and custom
+themes. An optional `appearance="light" | "dark"` prop lets a framing host override the
+colour intensity. Reduced motion renders a static field; hidden documents pause animation.
+All animation frames, resize observers, and theme listeners are removed on unmount.
+`Starfield` and `StarfieldHost` remain exported for existing consumers.
+
+The field is adapted from [matty-morgs/octo-space](https://github.com/matty-morgs/octo-space/blob/7f5536888eaf0068200e1d339318ba2bc57a5e40/onboarding-aura/index.html).
+
 <!-- original folds README follows -->
 
 # Folds

package/dist/components/index.d.ts

@@ -66,3 +66,4 @@ export * from "./surface-toolbar";
 export * from "./dock";
 export * from "./inspector-tabs";
 export * from "./activity-item";
+export * from "./orb-background";

package/dist/components/orb-background/OrbBackground.css.d.ts

@@ -0,0 +1,3 @@
+/** Isolate the decorative layer behind content and clip the blur at the surface edge. */
+export declare const OrbBackgroundHost: string;
+export declare const OrbBackground: string;

package/dist/components/orb-background/OrbBackground.d.ts

@@ -0,0 +1,7 @@
+export declare type OrbBackgroundProps = {
+    className?: string;
+    /** Optional framing-host override; otherwise follows the active surface token. */
+    appearance?: "light" | "dark";
+};
+/** Calm, blurred orbs with absorb collisions. Place inside an OrbBackgroundHost surface. */
+export declare const OrbBackground: ({ className, appearance }: OrbBackgroundProps) => JSX.Element;

package/dist/components/orb-background/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./OrbBackground";
+export { OrbBackgroundHost } from "./OrbBackground.css";

package/dist/components/orb-background/orbAppearance.d.ts

@@ -0,0 +1,2 @@
+/** Infer brightness from the resolved surface token, independent of consumer class names. */
+export declare const orbOpacityForSurface: (surface: string, prefersDark: boolean) => number;

package/dist/components/orb-background/orbField.d.ts

@@ -0,0 +1 @@
+export declare function startOrbField(element: HTMLCanvasElement): () => void;

package/dist/components/page/Page.d.ts

@@ -12,6 +12,12 @@ export declare type RoomNavToggleOptions = {
     animate?: boolean;
 };
 export declare function useRoomNavCollapsed(): [boolean, (options?: RoomNavToggleOptions) => void];
+/** Temporarily collapse the sidebar without writing its saved preference.
+ * Manual toggles win until this request ends. Changing scope starts a new request
+ * (for example, entering another room); switching surfaces in one scope does not.
+ * Call once from the layout owning the request, outside the collapsible content.
+ */
+export declare function useRoomNavAutoCollapse(active: boolean, scope?: string): void;
 declare type PageNavProps = ClientDrawerLayoutProps & css.PageNavVariants & {
     /** Decorative brand mark shown in the collapsed rail until hover or keyboard focus. */
     collapsedMark?: ReactNode;

package/dist/components/page/roomNavCollapseStore.d.ts

@@ -0,0 +1,7 @@
+/** One effective state shared by the sidebar and all of its manual controls. */
+export declare const createRoomNavCollapseStore: (storage: () => Pick<Storage, "getItem" | "setItem">) => {
+    getSnapshot: () => boolean;
+    subscribe: (listener: () => void) => () => void;
+    toggle: () => void;
+    requestCollapse: () => () => void;
+};