@netsapiens/horizon-sdk 0.1.2 → 0.1.3

package/README.md

@@ -29,18 +29,18 @@ Peer deps: `react ^18 || ^19`, `react-dom ^18 || ^19`, `loglevel ^1.9`.
 
 ```tsx
 // src/App.tsx
-import { useEffect } from 'react';
-import { type HorizonContext, useRemoteApp } from '@netsapiens/horizon-sdk';
-import MyButton from './extensions/MyButton';
+import { useEffect } from "react";
+import { type HorizonContext, useRemoteApp } from "@netsapiens/horizon-sdk";
+import MyButton from "./extensions/MyButton";
 
 export default function App(horizonContext: HorizonContext) {
-  const { sdk, user, theme } = useRemoteApp(horizonContext, 'my-app');
+  const { sdk, user, theme } = useRemoteApp(horizonContext, "my-app");
 
   useEffect(() => {
     sdk.registerDynamicExtension({
-      id: 'my-app.export-button',
-      zone: 'page-header-actions',
-      routes: [{ pattern: '/manage/*/call-logs' }],
+      id: "my-app.export-button",
+      zone: "page-header-actions",
+      routes: [{ pattern: "/manage/*/call-logs" }],
       component: MyButton,
     });
   }, [sdk]);
@@ -51,14 +51,20 @@ export default function App(horizonContext: HorizonContext) {
 
 ```tsx
 // src/extensions/MyButton.tsx
-import { type ExtensionComponentProps, useTheme } from '@netsapiens/horizon-sdk';
+import {
+  type ExtensionComponentProps,
+  useTheme,
+} from "@netsapiens/horizon-sdk";
 
 export default function MyButton({ context }: ExtensionComponentProps) {
   const { theme } = useTheme(context.eventBus); // reactive — no manual event wiring
   const { Button, Icon } = context.ui ?? {};
   if (!Button || !Icon) return null;
   return (
-    <Button startIcon={<Icon icon="mdi:download" />} onClick={() => alert('Exported!')}>
+    <Button
+      startIcon={<Icon icon="mdi:download" />}
+      onClick={() => alert("Exported!")}
+    >
       Export
     </Button>
   );
@@ -91,8 +97,11 @@ export default function MyButton({ context }: ExtensionComponentProps) {
 Register a full page route using the SDK. Wrap your page component in `HorizonContextProvider` so it gets a live, reactive context — including automatic dark mode — without any extra wiring.
 
 ```tsx
-import { HorizonContextProvider, useHorizonContext } from '@netsapiens/horizon-sdk';
-import MySettingsPage from './pages/MySettingsPage';
+import {
+  HorizonContextProvider,
+  useHorizonContext,
+} from "@netsapiens/horizon-sdk";
+import MySettingsPage from "./pages/MySettingsPage";
 
 // In your App component:
 const MySettingsRoute = useMemo(
@@ -109,12 +118,12 @@ const MySettingsRoute = useMemo(
 );
 
 sdk.registerRoute({
-  id: 'my-app.settings',
-  parentPath: '/home', // attach under Apps menu
-  path: 'my-settings', // → /home/my-settings
-  label: 'My Settings',
-  icon: 'mdi:cog',
-  placement: { after: 'settings' }, // position after the Settings item
+  id: "my-app.settings",
+  parentPath: "/home", // attach under Apps menu
+  path: "my-settings", // → /home/my-settings
+  label: "My Settings",
+  icon: "mdi:cog",
+  placement: { after: "settings" }, // position after the Settings item
   component: MySettingsRoute,
 });
 ```
@@ -125,12 +134,12 @@ Use `placement` to control where your route appears in the menu. You can positio
 
 ```tsx
 sdk.registerRoute({
-  id: 'my-app.settings',
-  parentPath: '/home',
-  path: 'my-settings',
-  label: 'My Settings',
-  icon: 'mdi:cog',
-  placement: { after: 'settings' }, // After the Settings item
+  id: "my-app.settings",
+  parentPath: "/home",
+  path: "my-settings",
+  label: "My Settings",
+  icon: "mdi:cog",
+  placement: { after: "settings" }, // After the Settings item
   component: MySettingsRoute,
 });
 ```
@@ -148,7 +157,7 @@ Inside the page component, read context with `useHorizonContext()` instead of ac
 
 ```tsx
 // src/pages/MySettingsPage.tsx
-import { useHorizonContext } from '@netsapiens/horizon-sdk';
+import { useHorizonContext } from "@netsapiens/horizon-sdk";
 
 export default function MySettingsPage() {
   const { ui, user, navigate, theme } = useHorizonContext();
@@ -156,10 +165,13 @@ export default function MySettingsPage() {
   const { Button, Stack, Typography } = ui;
 
   return (
-    <PageTemplate title="Settings" breadcrumbs={[{ label: 'Apps', url: '/apps' }]}>
+    <PageTemplate
+      title="Settings"
+      breadcrumbs={[{ label: "Apps", url: "/apps" }]}
+    >
       <Stack spacing={2}>
         <Typography variant="body1">Hello, {user.displayName}.</Typography>
-        <Button variant="contained" onClick={() => navigate('/apps')}>
+        <Button variant="contained" onClick={() => navigate("/apps")}>
           Back
         </Button>
       </Stack>
@@ -179,9 +191,14 @@ If your route component lives in a separate exposed module, use `useRouteFromMod
 ```tsx
 const { loading, error } = useRouteFromModule(
   horizonContext.eventBus,
-  'my-app',
-  { id: 'my-app.settings', parentPath: '/home', path: 'my-settings', label: 'My Settings' },
-  { scope: 'myApp', module: './SettingsPage' },
+  "my-app",
+  {
+    id: "my-app.settings",
+    parentPath: "/home",
+    path: "my-settings",
+    label: "My Settings",
+  },
+  { scope: "myApp", module: "./SettingsPage" },
 );
 ```
 
@@ -191,31 +208,31 @@ Extensions render at named **zones** on routes that match a **pattern**. You don
 
 ```tsx
 sdk.registerDynamicExtension({
-  id: 'my-app.row-action',
-  zone: 'table-row-actions',
-  routes: [{ pattern: '/manage/*/call-logs' }],
-  priority: 10, // higher = first 
-  requiredPermissions: ['calls:read'],
-  condition: (ctx) => ctx.user.domain === 'special.com',
+  id: "my-app.row-action",
+  zone: "table-row-actions",
+  routes: [{ pattern: "/manage/*/call-logs" }],
+  priority: 10, // higher = first
+  requiredPermissions: ["calls:read"],
+  condition: (ctx) => ctx.user.domain === "special.com",
   component: RowAction,
 });
 ```
 
 **Available zones:**
 
-| Zone                       | Where it renders                             |
-| -------------------------- | -------------------------------------------- |
-| `page-header-actions`      | Right side of any page header                |
-| `page-header-secondary`    | Subtitle row of page header (badges, status) |
-| `page-content-before`      | Above main page content                      |
-| `page-content-after`       | Below main page content                      |
-| `page-sidebar`             | Page sidebar                                 |
-| `table-toolbar`            | Above any DataGrid                           |
-| `table-row-actions`        | Per-row action column                        |
-| `detail-panel-tabs`        | Detail-panel tab strip                       |
-| `detail-panel-actions`     | Detail-panel action area                     |
-| `topbar-actions`           | Global top app bar (after comms, before utilities) |
-| `inbound-call-content`     | Incoming-call notification body              |
+| Zone                    | Where it renders                                                               |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `page-header-actions`   | Right side of any page header                                                  |
+| `page-header-secondary` | Subtitle row of page header (badges, status)                                   |
+| `page-content-after`    | Below main page content                                                        |
+| `sidetray`              | Side tray panel (open/close via host toggle)                                   |
+| `table-toolbar`         | Above any DataGrid                                                             |
+| `table-filter-bar`      | Filter chips inline with search bar; pass a row predicate via `onFilterChange` |
+| `table-row-actions`     | Per-row action column                                                          |
+| `detail-panel-tabs`     | Detail-panel tab strip                                                         |
+| `detail-panel-actions`  | Detail-panel action area                                                       |
+| `topbar-actions`        | Global top app bar (after comms, before utilities)                             |
+| `inbound-call-content`  | Incoming-call notification body                                                |
 
 > **Note**: Check Platform → UI SDK Management → SDK Settings for the current list of available zones and their descriptions.
 
@@ -233,26 +250,102 @@ Custom zones (any string) work for pages that explicitly render `<DynamicExtensi
 Hook form:
 
 ```tsx
-useDynamicExtension(horizonContext.eventBus, 'my-app', {
-  id: 'my-app.banner',
-  zone: 'page-content-before',
-  routes: [{ pattern: '/manage/:domain/users' }],
+useDynamicExtension(horizonContext.eventBus, "my-app", {
+  id: "my-app.banner",
+  zone: "page-content-after",
+  routes: [{ pattern: "/manage/:domain/users" }],
   component: Banner,
 });
 ```
 
+#### table-filter-bar zone
+
+Pages that render a filter bar (e.g. active calls, hardphone devices) expose a
+`TableFilterBarContext` via `context.pageContext`. Extensions in this zone render
+alongside the host's built-in filter chips and can drive row-level filtering by
+passing a **predicate function** to `onFilterChange`. The host applies the function
+generically — your extension owns the filtering logic, not the host.
+
+```tsx
+import { useState } from "react";
+import type {
+  ExtensionComponentProps,
+  TableFilterBarContext,
+} from "@netsapiens/horizon-sdk";
+
+export function VipFilter({ context }: ExtensionComponentProps) {
+  const filterCtx = context.pageContext as TableFilterBarContext | undefined;
+  const { ToggleButtonGroup } = context.ui ?? {};
+  const [active, setActive] = useState(false);
+
+  function handleChange(_e: React.SyntheticEvent, value: string | null) {
+    const next = value === "vip";
+    setActive(next);
+    if (next) {
+      filterCtx?.onFilterChange((row) => {
+        const r = row as Record<string, unknown>;
+        return r["customer-tier"] === "vip";
+      });
+    } else {
+      filterCtx?.onFilterChange(null); // clear — show all rows
+    }
+  }
+
+  if (!ToggleButtonGroup) return null;
+
+  return (
+    <ToggleButtonGroup
+      value={active ? "vip" : null}
+      exclusive
+      onChange={handleChange}
+      options={[{ value: "vip", label: "VIP Only" }]}
+    />
+  );
+}
+
+// Register against any page that exposes a filter bar
+sdk.registerDynamicExtension({
+  id: "my-app.vip-filter",
+  zone: "table-filter-bar",
+  routes: [{ pattern: "/manage/:domain/call-logs" }],
+  component: VipFilter,
+});
+```
+
+`TableFilterBarContext` fields:
+
+| Field            | Type                                                      | Description                                           |
+| ---------------- | --------------------------------------------------------- | ----------------------------------------------------- |
+| `onFilterChange` | `(filterFn: ((row: unknown) => boolean) \| null) => void` | Pass a predicate to filter rows; pass `null` to clear |
+
+**Important:** track active/inactive state locally with `useState` in your component —
+`TableFilterBarContext` does not expose the current filter state back to you.
+
+> **React `useState` gotcha** — never pass a filter function directly to `setState`:
+>
+> ```ts
+> // ❌ React treats functions as lazy initializers, calling fn(prevState)
+> setMyFilter(filterFn);
+>
+> // ✅ Wrap in an arrow function so React stores the function, not its return value
+> setMyFilter(() => filterFn);
+> ```
+>
+> This only affects you if you're storing the filter function in your own component state.
+> The host DataTable handles this correctly internally.
+
 ### Dynamic table columns
 
 Add columns to host DataGrids that opt in (zone names like `call-logs-columns`, `users-columns`, etc.):
 
 ```tsx
 sdk.registerDynamicColumn({
-  id: 'my-app.priority',
-  zone: 'call-logs-columns',
-  routes: [{ pattern: '/manage/*/call-logs' }],
+  id: "my-app.priority",
+  zone: "call-logs-columns",
+  routes: [{ pattern: "/manage/*/call-logs" }],
   column: {
-    field: 'priority',
-    headerName: 'Priority',
+    field: "priority",
+    headerName: "Priority",
     width: 120,
     sortable: true,
     filterable: true,
@@ -274,7 +367,7 @@ The recommended pattern uses `useHorizonContext()` (see Routes above). The old p
 
 ```tsx
 // Recommended — page component using the hook (fully reactive theme)
-import { useHorizonContext } from '@netsapiens/horizon-sdk';
+import { useHorizonContext } from "@netsapiens/horizon-sdk";
 
 export default function MyPage() {
   const { ui, user } = useHorizonContext();
@@ -282,7 +375,10 @@ export default function MyPage() {
   const { Button, Stack, Typography } = ui;
 
   return (
-    <PageTemplate title="My Page" breadcrumbs={[{ label: 'Apps', url: '/apps' }]}>
+    <PageTemplate
+      title="My Page"
+      breadcrumbs={[{ label: "Apps", url: "/apps" }]}
+    >
       <Stack spacing={2}>
         <Typography variant="h5">Hello, {user.displayName}</Typography>
         <Button variant="contained">Action</Button>
@@ -302,11 +398,11 @@ function MyButton({ context }: ExtensionComponentProps) {
 
 Available under `horizonContext.ui` (or via `useHorizonContext().ui`):
 
-- `templates`: `PageTemplate`, `PageTemplateWithExtensions`, `FormTemplate`, `SideTrayTemplate`, `DatagridTemplate`
+- `templates`: `PageTemplate`, `PageTemplateWithExtensions`, `FormTemplate`, `SidePanel`, `FormPanel`, `DatagridTemplate`
 
 > **`DatagridTemplate` and the MUI X Pro license** — `DatagridTemplate` wraps MUI's `DataGridPro` internally, which is a paid licensed component. The license is held by the Horizon host; **you do not need an MUI X Pro license** and must not import `@mui/x-data-grid-pro` directly in your remote app. Always use `DatagridTemplate` from the SDK.
 
-- Form: `Button`, `IconButton`, `TextField`, `Select`, `Checkbox`, `Radio`, `RadioGroup`, `Switch`, `ToggleButton`, `ToggleButtonGroup`, `FormLabel`
+- Form: `Button`, `IconButton`, `TextField`, `Select`, `Checkbox`, `Radio`, `RadioGroup`, `Switch`, `ToggleButton`, `ToggleButtonGroup`, `FormLabel`, `FormControlLabel`
 - Display: `Typography`, `Chip`, `Avatar`, `Divider`, `Tooltip`, `Icon`
 - Layout: `Stack`, `Paper`
 - Feedback: `Alert`
@@ -331,6 +427,80 @@ The TypeScript types reject the children pattern at compile time. If you ever se
 
 Other themed components (`Button`, `Stack`, `Paper`, etc.) follow the standard MUI children pattern.
 
+#### SidePanel & FormPanel — right-side drawers
+
+`SidePanel` and `FormPanel` are the shared right-drawer components Horizon uses
+for its own add/edit forms and detail panels. Reach for these when building a
+right-side drawer so it matches the host exactly and picks up the
+`form-section-*` extension zones automatically.
+
+**`SidePanel`** — the drawer shell (sticky header, scrollable body, optional
+sticky footer). Use for detail/view/settings panels:
+
+```tsx
+const { SidePanel } = ui.templates;
+
+<SidePanel
+  open={open}
+  onClose={() => setOpen(false)}
+  title="Details"
+  subtitle="Read-only"
+  width="lg" // 'sm' | 'md' | 'lg' | 'xl'
+  footer={<Button onClick={() => setOpen(false)}>Close</Button>}
+>
+  {/* body */}
+</SidePanel>;
+```
+
+**`FormPanel`** — `SidePanel` + a `<form>`, a Submit/Cancel footer, and the
+`form-section-before` / `form-section-after` extension zones built in:
+
+```tsx
+const { FormPanel } = ui.templates;
+
+<FormPanel
+  open={open}
+  onClose={() => setOpen(false)}
+  title="Add widget"
+  formType="widget" // identifies the form to extensions
+  mode="add" // 'add' | 'edit'
+  formData={values} // live values handed to extensions
+  onSubmit={(e) => {
+    e?.preventDefault();
+    save(values);
+  }}
+  submitLabel="Add"
+  isSubmitting={pending}
+  error={error}
+>
+  {/* field sections */}
+</FormPanel>;
+```
+
+**Multi-step wizard** — pass `steps` instead of `children`; FormPanel renders the
+stepper header and a Back/Next/Submit footer. Each step's optional `validate`
+gates forward navigation (return `boolean | Promise<boolean>`):
+
+```tsx
+<FormPanel
+  open={open}
+  onClose={() => setOpen(false)}
+  title="Setup"
+  formType="setup"
+  mode="add"
+  onSubmit={handleSubmit(onValid)}
+  isComplete={isValid} // offer Submit before the last step
+  steps={[
+    {
+      label: "Basics",
+      content: <BasicsStep />,
+      validate: () => trigger(["name"]),
+    },
+    { label: "Options", content: <OptionsStep /> },
+  ]}
+/>
+```
+
 ---
 
 ## Dark mode
@@ -340,7 +510,7 @@ Dark mode is handled automatically — **you write no theme-switching code for M
 MUI components (`Button`, `Paper`, `Stack`, `DatagridTemplate`, etc.) inherit the host's Aurora ThemeProvider via the shared module singleton and switch the moment the user toggles the theme. For any conditional logic that reads the theme string (custom colors, conditional icons, etc.), use `useTheme()`:
 
 ```tsx
-import { useTheme } from '@netsapiens/horizon-sdk';
+import { useTheme } from "@netsapiens/horizon-sdk";
 ```
 
 `useTheme()` is a single hook that works identically in both contexts:
@@ -354,14 +524,16 @@ import { useTheme } from '@netsapiens/horizon-sdk';
 // Page component
 export default function MyPage() {
   const { theme } = useTheme(); // no argument needed inside HorizonContextProvider
-  return <div style={{ background: theme === 'dark' ? '#1B2124' : '#fff' }}>...</div>;
+  return (
+    <div style={{ background: theme === "dark" ? "#1B2124" : "#fff" }}>...</div>
+  );
 }
 
 // Extension component
 export default function MyButton({ context }: ExtensionComponentProps) {
   const { theme } = useTheme(context.eventBus); // pass eventBus for extensions
   const { Button } = context.ui ?? {};
-  return <Button>{theme === 'dark' ? '🌙' : '☀️'} Export</Button>;
+  return <Button>{theme === "dark" ? "🌙" : "☀️"} Export</Button>;
 }
 ```
 
@@ -373,9 +545,11 @@ export default function MyButton({ context }: ExtensionComponentProps) {
 
 ```tsx
 const { api, user } = horizonContext;
-const devices = await api.get(`/domains/${user.domain}/users/${user.displayName}/devices`);
+const devices = await api.get(
+  `/domains/${user.domain}/users/${user.displayName}/devices`,
+);
 await api.post(`/domains/${user.domain}/users/${user.displayName}/contacts`, {
-  'name-first-name': 'John',
+  "name-first-name": "John",
 });
 ```
 
@@ -389,9 +563,9 @@ For cross-app messages and host events:
 
 ```tsx
 useEffect(() => {
-  const handler = (data: unknown) => console.log('theme changed', data);
-  horizonContext.eventBus.on('theme:changed', handler);
-  return () => horizonContext.eventBus.off('theme:changed', handler);
+  const handler = (data: unknown) => console.log("theme changed", data);
+  horizonContext.eventBus.on("theme:changed", handler);
+  return () => horizonContext.eventBus.off("theme:changed", handler);
 }, []);
 ```
 
@@ -426,25 +600,30 @@ During local development the webpack dev server sets `Access-Control-Allow-Origi
 Use webpack Module Federation. Minimal `webpack.config.js`:
 
 ```js
-const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');
+const ModuleFederationPlugin = require("webpack/lib/container/ModuleFederationPlugin");
 
 module.exports = (_env, argv) => ({
-  entry: './src/App.tsx',
-  output: { publicPath: 'auto', filename: 'remoteEntry.js', clean: true },
-  resolve: { extensions: ['.tsx', '.ts', '.js'] },
+  entry: "./src/App.tsx",
+  output: { publicPath: "auto", filename: "remoteEntry.js", clean: true },
+  resolve: { extensions: [".tsx", ".ts", ".js"] },
   module: {
-    rules: [{ test: /\.(tsx?|jsx?)$/, exclude: /node_modules/, use: 'babel-loader' }],
+    rules: [
+      { test: /\.(tsx?|jsx?)$/, exclude: /node_modules/, use: "babel-loader" },
+    ],
   },
   plugins: [
     new ModuleFederationPlugin({
-      name: 'myApp', // your Extension App ID — must match exactly what you enter during registration
-      filename: 'remoteEntry.js',
-      exposes: { './App': './src/App' },
+      name: "myApp", // your Extension App ID — must match exactly what you enter during registration
+      filename: "remoteEntry.js",
+      exposes: { "./App": "./src/App" },
       shared: {
-        react: { singleton: true, requiredVersion: '^19.0.0' },
-        'react-dom': { singleton: true, requiredVersion: '^19.0.0' },
-        loglevel: { singleton: true, requiredVersion: '^1.9.0' },
-        '@netsapiens/horizon-sdk': { singleton: true, requiredVersion: '^1.0.0' },
+        react: { singleton: true, requiredVersion: "^19.0.0" },
+        "react-dom": { singleton: true, requiredVersion: "^19.0.0" },
+        loglevel: { singleton: true, requiredVersion: "^1.9.0" },
+        "@netsapiens/horizon-sdk": {
+          singleton: true,
+          requiredVersion: "^1.0.0",
+        },
 
         // Do NOT add @mui/material, @emotion/*, or @mui/x-data-grid-pro here.
         // The host's federation loader does not register MUI as a shared module,
@@ -455,7 +634,7 @@ module.exports = (_env, argv) => ({
       },
     }),
   ],
-  devServer: { port: 5005, headers: { 'Access-Control-Allow-Origin': '*' } },
+  devServer: { port: 5005, headers: { "Access-Control-Allow-Origin": "*" } },
 });
 ```
 
@@ -594,10 +773,10 @@ Use **Disable** when you need to take an app offline temporarily (maintenance, i
 Throw and catch typed errors with codes:
 
 ```tsx
-import { HorizonSDKError, apiError } from '@netsapiens/horizon-sdk';
+import { HorizonSDKError, apiError } from "@netsapiens/horizon-sdk";
 
 try {
-  await api.get('/...');
+  await api.get("/...");
 } catch (err) {
   if (HorizonSDKError.isHorizonSDKError(err)) {
     console.error(err.code, err.getUserMessage());