@q9labsai/chalk-react 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Q9Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# @q9labsai/chalk-react
+
+`@q9labsai/chalk-react` provides the React surface for a Chalk Space. Use
+`<Chalk />` for the complete embedded experience, or share a `SpaceClient`
+with `<ChalkProvider>` and the snapshot hooks when building custom UI.
+
+## Installation
+
+```bash
+pnpm add @q9labsai/chalk-client @q9labsai/chalk-react
+```
+
+## Turnkey UI
+
+Provide a Space slug and a `getAccess` callback. Chalk creates and owns the
+client, renders the Entrance by default, and releases its owned client when it
+unmounts.
+
+```tsx
+import { Chalk } from "@q9labsai/chalk-react";
+import type { AccessGrant } from "@q9labsai/chalk-client";
+
+export function SpacePage() {
+  return (
+    <Chalk
+      space="design-review"
+      getAccess={async ({ space, reason }): Promise<AccessGrant> => fetchAccess({ space, reason })}
+      defaults={{ microphone: true, camera: true }}
+      features={{ chat: true, screenShare: true, reactions: true }}
+      spaceName="Design review"
+      onEpisodeEnded={({ episode }) => console.log(episode?.id)}
+    />
+  );
+}
+```
+
+Pass an existing client when its lifecycle belongs to the embedding
+application. Chalk will use it without disposing it.
+
+```tsx
+<Chalk client={spaceClient} entrance={false} />
+```
+
+`theme` is the only styling door. It accepts a closed token-key set, which
+Chalk emits as CSS custom properties scoped to its root. Size and place Chalk
+with its parent element.
+
+`colorScheme` accepts `light`, `dark`, or `system`. With `system`, Chalk follows
+the browser preference while keeping explicit token overrides in place.
+
+```tsx
+<Chalk
+  client={spaceClient}
+  theme={{
+    colorScheme: "dark",
+    accent: "#4b9bb8",
+    tokens: { canvas: "#152127", surface: "#1d2b31" },
+  }}
+/>
+```
+
+## Custom UI
+
+`ChalkProvider` only shares a `SpaceClient` with React. It does not join,
+leave, refresh access, or own the client’s lifetime.
+
+```tsx
+import type { SpaceClient } from "@q9labsai/chalk-client";
+import { ChalkProvider, useCan, useParticipants, useSpaceClient } from "@q9labsai/chalk-react";
+
+function ParticipantPanel() {
+  const client = useSpaceClient();
+  const { roster } = useParticipants();
+  const canRaiseHand = useCan("raiseHand");
+
+  return (
+    <>
+      <p>{roster.length} participants</p>
+      {canRaiseHand ? <button onClick={() => void client.participants.raiseHand()}>Raise hand</button> : null}
+    </>
+  );
+}
+
+export function SpacePanel({ client }: { readonly client: SpaceClient }) {
+  return (
+    <ChalkProvider client={client}>
+      <ParticipantPanel />
+    </ChalkProvider>
+  );
+}
+```
+
+The public hook set is closed: `useSpaceClient`, `useConnection`, `useSelf`,
+`useParticipants`, `useMedia`, `useChat`, `useReactions`, `useWhiteboard`, and
+`useCan`. Each snapshot hook returns its stable `SpaceSnapshot` slice; use the
+client hook for commands.
+
+`AccessGrant` remains opaque. The application backend creates it, `getAccess`
+returns it unchanged, and `SpaceClient` handles refresh and recovery.

package/dist/__tests__/setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/__tests__/setup.ts"],"names":[],"mappings":""}

package/dist/bindings/context.d.ts

@@ -0,0 +1,9 @@
+import type { SpaceClient } from "@q9labsai/chalk-client";
+import { type PropsWithChildren } from "react";
+import type React from "react";
+export declare const SpaceClientContext: React.Context<SpaceClient | null>;
+export type ChalkProviderProps = PropsWithChildren<{
+    readonly client: SpaceClient;
+}>;
+export declare function ChalkProvider({ children, client }: ChalkProviderProps): React.JSX.Element;
+//# sourceMappingURL=context.d.ts.map

package/dist/bindings/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/bindings/context.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC9D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,eAAO,MAAM,kBAAkB,mCAA0C,CAAC;AAE1E,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,CAAC,CAAC;AAEH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,kBAAkB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAEzF"}

package/dist/bindings/hooks.d.ts

@@ -0,0 +1,11 @@
+import type { Capability, ChatSlice, ConnectionSlice, MediaSlice, ParticipantsSlice, ReactionsSlice, SelfSlice, SpaceClient, WhiteboardSlice } from "@q9labsai/chalk-client";
+export declare function useSpaceClient(): SpaceClient;
+export declare function useConnection(): ConnectionSlice;
+export declare function useSelf(): SelfSlice;
+export declare function useParticipants(): ParticipantsSlice;
+export declare function useMedia(): MediaSlice;
+export declare function useChat(): ChatSlice;
+export declare function useReactions(): ReactionsSlice;
+export declare function useWhiteboard(): WhiteboardSlice;
+export declare function useCan(capability: Capability): boolean;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/bindings/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/bindings/hooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAiB,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAqB5L,wBAAgB,cAAc,IAAI,WAAW,CAQ5C;AAED,wBAAgB,aAAa,IAAI,eAAe,CAE/C;AAED,wBAAgB,OAAO,IAAI,SAAS,CAEnC;AAED,wBAAgB,eAAe,IAAI,iBAAiB,CAEnD;AAED,wBAAgB,QAAQ,IAAI,UAAU,CAErC;AAED,wBAAgB,OAAO,IAAI,SAAS,CAEnC;AAED,wBAAgB,YAAY,IAAI,cAAc,CAE7C;AAED,wBAAgB,aAAa,IAAI,eAAe,CAE/C;AAED,wBAAgB,MAAM,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAEtD"}