smartsell-ui-kit 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,22 @@
-MIT License
+SmartSell Proprietary License
 
-Copyright (c) 2026 SmartSell
+Copyright (c) 2026 SmartSell. All rights reserved.
 
-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:
+This source code, the published package artifacts, and all related documentation
+are proprietary software owned by SmartSell.
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Permission to access, install, and use this software is granted only to people
+and organizations that are explicitly authorized by SmartSell under a valid
+written agreement or commercial relationship.
+
+Except where SmartSell has given prior written permission, you may not copy,
+modify, merge, publish, distribute, sublicense, sell, lease, reverse engineer,
+decompile, create derivative works from, or otherwise exploit this software or
+any portion of it.
 
 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.
+FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. IN NO EVENT
+SHALL SMARTSELL OR ITS LICENSORS 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 OF THE SOFTWARE.

package/README.md

@@ -1,23 +1,40 @@
 # smartsell-ui-kit
 
-`smartsell-ui-kit` is the public UI primitives package for SmartSell Sales custom modules.
+`smartsell-ui-kit` is the shared React component package for SmartSell custom modules, tenant extensions, and isolated integrations.
 
-It is designed for tenant developers who should not need to know how the core app is implemented.
-The package stays on the public contract surface:
+It provides the public UI contract that external consumers should rely on instead of importing private SmartSell app internals. The package is built around a few core goals:
 
 - theme-aware components powered by `smartsell-theme`
-- inline-style primitives that do not depend on private app CSS files
-- a composable modal helper with predictable slot ids for `header`, `body`, and `footer`
+- self-contained styling with no dependency on private SmartSell CSS files
+- predictable APIs for forms, modals, data tables, and common surfaces
+- async-friendly primitives for remote search and server-driven datasets
+
+## Highlights
+
+- React 18-first component API
+- Consistent theme integration through `smartsell-theme`
+- Form primitives such as `Input`, `Textarea`, `Checkbox`, `DatePicker`, `Select`, and `SelectAsync`
+- Display and layout primitives such as `Card`, `CardSmall`, and `Separator`
+- Modal helpers including `Modal`, `ComposableModal`, and `createModalSlotIds`
+- Data components including `Table` and `TableAsync`
+- Brand images published from the dedicated `smartsell-ui-kit/img` subpath
+- Local Storybook workspace for visual QA before release
+
+## Requirements
+
+- React 18+
+- React DOM 18+
+- `smartsell-theme`
 
 ## Installation
 
 ```bash
-npm install react smartsell-theme smartsell-ui-kit
+npm install react@^18 react-dom@^18 smartsell-theme smartsell-ui-kit
 ```
 
-If you want to connect `ComposableModal` to SmartSell slot overrides, install `smartsell-sales-sdk` as well.
+## Quick start
 
-## Basic button and card
+Wrap your module with `ThemeProvider` from `smartsell-theme`, then consume the UI kit components normally.
 
 ```tsx
 import { ThemeProvider } from 'smartsell-theme';
@@ -36,33 +53,79 @@ export default function ExamplePage() {
 }
 ```
 
+## Main exports
+
+- `Button`, `Checkbox`, `DatePicker`, `Input`, `Textarea`, `Select`, `SelectAsync`
+- `Card`, `CardSmall`, `Separator`
+- `Modal`, `ComposableModal`, `createModalSlotIds`
+- `Table`, `TableAsync`
+- `useUiKitTheme`
+- `smartsell-ui-kit/img` for branded logo, icon, favicon, and background image components
+
+## Images subpath
+
+Import brand images from the dedicated `img` subpath so the main entrypoint stays focused on UI primitives.
+
+```tsx
+import { Icon192, Logo, Texture1 } from 'smartsell-ui-kit/img';
+
+export default function BrandHeader() {
+  return (
+    <div style={{ display: 'grid', gap: 16 }}>
+      <Logo style={{ width: 240 }} />
+      <Icon192 size={72} alt="SmartSell app icon" />
+      <Texture1 decorative style={{ width: '100%', maxWidth: 420 }} />
+    </div>
+  );
+}
+```
+
+All image components resolve their source from the active `smartsell-theme` context. Right now light and dark modes point to the same files, but the submodule already swaps sources by theme variant so future dark-specific images only require changing the mapped filenames.
+
 ## Composable modal pattern
 
-Use `ComposableModal` when you want the page to keep modal state while tenants customize visual sections independently.
+Use `ComposableModal` when the page should own modal state and business logic, while host applications or extension layers customize the `header`, `body`, and `footer` through stable slot ids.
 
 ```tsx
-import { SlotRenderer, type ModulePageProps, type SlotComponentProps } from 'smartsell-sales-sdk';
-import { ComposableModal, createModalSlotIds } from 'smartsell-ui-kit';
+import { useState } from 'react';
+
+import { Button, ComposableModal, createModalSlotIds } from 'smartsell-ui-kit';
 
 const slotIds = createModalSlotIds('order-review');
 
-export default function ExamplePage({ sdk }: ModulePageProps) {
+export default function ExamplePage() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  const submitOrder = () => {
+    setIsOpen(false);
+  };
+
   return (
-    <ComposableModal
-      isOpen={isOpen}
-      onClose={() => setIsOpen(false)}
-      onConfirm={submitOrder}
-      title="Order review"
-      slotBaseId="order-review"
-      renderSlot={({ id, context, children }) => (
-        <SlotRenderer id={id} sdk={sdk} context={context}>
-          {children}
-        </SlotRenderer>
-      )}
-      payload={{ orderNumber: 'SO-1001', total: 421.9 }}
-    >
-      <div>Default modal body</div>
-    </ComposableModal>
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open order review</Button>
+
+      <ComposableModal
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        onConfirm={submitOrder}
+        title="Order review"
+        slotBaseId="order-review"
+        renderSlot={({ id, context, children }) => {
+          if (id === slotIds.footer) {
+            return (
+              <Button onClick={() => context.confirm?.()}>
+                Send order {context.payload?.orderNumber}
+              </Button>
+            );
+          }
+
+          return children;
+        }}
+        payload={{ orderNumber: 'SO-1001', total: 421.9 }}
+      >
+        <div>Default modal body</div>
+      </ComposableModal>
+    </>
   );
 }
 ```
@@ -73,81 +136,92 @@ Slot ids generated by `createModalSlotIds('order-review')`:
 - `order-review:modal-body`
 - `order-review:modal-footer`
 
-Tenant extension example:
+This pattern is useful when:
+
+- the page owns data loading, permissions, and submission flow
+- the host app needs stable extension points instead of private imports
+- multiple modal variants should reuse the same contract
+
+## Async components
+
+`SelectAsync` is designed for remote option sources while preserving the same interaction model as the regular `Select`.
 
 ```tsx
-import {
-  defineExtensionManifest,
-  type ExtensionManifest,
-  type SlotComponentProps,
-} from 'smartsell-sales-sdk';
-import {
-  Button,
-  type ModalSlotContext,
-  createModalSlotIds,
-} from 'smartsell-ui-kit';
-
-type OrderPayload = {
-  orderNumber: string;
-  total: number;
-};
-
-function CustomFooter({ sdk, context }: SlotComponentProps<ModalSlotContext<OrderPayload>>) {
+import { useState } from 'react';
+
+import { SelectAsync, type SelectAsyncOption } from 'smartsell-ui-kit';
+
+type CustomerOption = SelectAsyncOption<string>;
+
+function CustomerField() {
+  const [value, setValue] = useState<CustomerOption | null>(null);
+
   return (
-    <Button onClick={() => context?.confirm?.()}>
-      Send order {context?.payload?.orderNumber}
-    </Button>
+    <SelectAsync
+      label="Customer"
+      value={value}
+      onChange={setValue}
+      loadOptions={async (query, loadedOptions, { page, signal }) => {
+        const response = await fetch(`/api/customers?search=${query}&page=${page}`, { signal });
+        const data = await response.json();
+
+        return {
+          options: data.items.map((item: { id: string; tradeName: string }) => ({
+            value: item.id,
+            label: item.tradeName,
+          })),
+          hasMore: data.hasMore,
+        };
+      }}
+    />
   );
 }
+```
 
-const slots = createModalSlotIds('order-review');
-
-const manifest: ExtensionManifest = defineExtensionManifest({
-  slots: {
-    [slots.footer]: {
-      action: 'replace',
-      component: CustomFooter,
-    },
-  },
-});
+`TableAsync` follows the same idea for remote datasets, with debounced search and request cancellation support built into the component flow.
 
-export default manifest;
-```
+## Development workflow
 
-## Why this modal pattern exists
+Useful local commands:
 
-- The page owns state, data loading, and permissions.
-- The tenant customizes `header`, `body`, and `footer` through stable slot ids.
-- Slot overrides receive an explicit `context` object instead of relying on private core imports.
-- The same pattern works for many modals without creating a new module type.
+```bash
+npm run storybook
+npm run test
+npm run validate
+npm run validate:release
+```
 
-## Publish
+Run Storybook in Docker when you want containerized local development:
 
 ```bash
-npm run typecheck
-npm run build
-npm publish
+docker compose up --build
 ```
 
-## Component preview workspace
+## Storybook workspace
 
-The repository now includes a local Storybook workspace so you can inspect and interact with components before publishing the package.
+The repository includes a local Storybook workspace for component review and design QA.
 
-- grouped sidebar navigation for buttons, surfaces, forms, and modals
-- live Controls for component props such as size, variants, labels, states, and modal behaviors
-- a mocked `ThemeProvider` so components render with the same theme contract used in host apps
+- grouped navigation for buttons, surfaces, forms, modals, and tables
+- a dedicated `Images` section covering logos, icons, and backgrounds from `smartsell-ui-kit/img`
+- live Controls for props and responsive behavior
+- a local `ThemeProvider` preview using the same `smartsell-theme` contract expected by host apps
+- a `Theme/Colors` playground for temporary Storybook-only token overrides
 
-Run it directly with npm:
+Storybook is development-only. It is not published to npm because the package only ships `dist`, `README.md`, and `LICENSE`.
 
-```bash
-npm install
-npm run storybook
-```
+Theme overrides from the `Theme/Colors` story affect only the local Storybook session. Runtime consumers still read theme values from their host application's `smartsell-theme` integration.
+
+## Release checklist
 
-Run it in a container with hot reload:
+Before publishing a new version:
 
 ```bash
-docker compose up --build
+npm run validate
+npm run build:storybook
+npm pack --dry-run
+npm publish
 ```
 
-The Storybook workspace is development-only. It is not part of the published package because `package.json` only ships `dist`, `README.md`, and `LICENSE`.
+## License
+
+This package is distributed under the SmartSell proprietary license described in `LICENSE`.