infaira-canvas 0.1.9

package/templates/README.md

@@ -0,0 +1,127 @@
+# ICan Widget
+
+A widget for the **InfAIra Canvas (ICan)**, scaffolded with
+[`infaira-canvas`](https://www.npmjs.com/package/infaira-canvas).
+
+> Update this title and description with your widget’s name once you’ve had a
+> chance to read through the file map below.
+
+---
+
+## Quick Start
+
+```bash
+npm install                    # install dependencies (already done by init)
+npm run dev                    # local dev harness on http://localhost:8080
+npm run build                  # produces dist/main.js (this is what you upload)
+```
+
+When you’re happy with the result, upload `bundle.json` + `dist/main.js` to your
+ICan portal’s **Widget Library** page (or via the API).
+
+> Anything you see in `npm run dev` will look identical in the portal — the
+> harness mirrors the portal’s component library.
+
+---
+
+## What goes where
+
+| Path                              | What it does                                                         |
+|-----------------------------------|----------------------------------------------------------------------|
+| **`src/index.tsx`**               | Your widget — edit this. Register it via `registerWidget(...)`.       |
+| **`src/styles.scss`**             | Theme-aware SCSS. Use `--ican-*` CSS vars, never hardcoded colors.    |
+| **`src/ican.ts`**                 | Helper that exposes `registerWidget` + `IContextProvider` types.      |
+| `bundle.json`                     | Widget metadata (id, name, version, layout). Uploaded with the build. |
+| `dist/main.js`                    | Webpack output. This is what the portal loads at runtime.             |
+| `index.html`                      | Dev harness — loads `dist/main.js` + the ICan component mock.         |
+| `ui.html`                         | Alternate harness for UI/display preview.                             |
+| `resources/ican-components.js`    | Local mock of `ican/components` — mirrors portal behaviour.           |
+| `resources/infaira-*.png`, favicon | Branding assets used by the dev harness.                              |
+| `ican.d.ts`                       | TypeScript types for `ican/components`. Don’t edit; comes from server.|
+| `designer.d.ts`                   | TypeScript types for the designer surface.                            |
+| `webpack.config.js`               | Build config. Externalises React + ICanComponents.                    |
+| `tsconfig.json`                   | TypeScript config.                                                    |
+| `package.json`                    | npm scripts + deps for this widget.                                   |
+| `localization.json`               | i18n strings (key → translation).                                     |
+| `site.webmanifest`                | PWA manifest used by the dev harness.                                 |
+| `sample-bundle.json`              | Example reference for `bundle.json`.                                  |
+| `sample-localization.json`        | Example reference for `localization.json`.                            |
+
+### Documentation
+
+| Doc                                                       | Read when…                                              |
+|-----------------------------------------------------------|---------------------------------------------------------|
+| **[ICan-Widget-Development-Guide.md](./ICan-Widget-Development-Guide.md)** | …you’re fetching data, adding a settings panel, using roles/localisation, or need multi-instance state patterns. |
+| **[ICan-Widget-Theming-Guide.md](./ICan-Widget-Theming-Guide.md)** | …you’re writing CSS — full reference of `--ican-*` vars across the four themes. |
+| **[ICan-Customizing-Components.md](./ICan-Customizing-Components.md)** | …you’re passing `style` / `className` to ICan components. |
+| **[ICan-Widget-Styling-Patterns.md](./ICan-Widget-Styling-Patterns.md)** | …you’re deciding how to approach CSS isolation, class name collisions, or glass theme support. |
+
+---
+
+## The Three Customization Patterns
+
+1. **ICan component + your `style` prop** — quick inline overrides:
+   `<Card style={{ background: 'var(--ican-accent-dim)' }}>`
+2. **Build your own elements** — raw `<div>` + SCSS using ICan CSS vars.
+3. **ICan component + `className` AND `style`** — `className` for structural rules
+   in SCSS, `style` for one-off tweaks.
+
+See [`ICan-Customizing-Components.md`](./ICan-Customizing-Components.md) for the
+full breakdown including merge order and when to use which layer.
+
+---
+
+## Theming Quick Rules
+
+- **Never hardcode a color.** Always go through `var(--ican-*)` so all four
+  themes (Dark / Light / Glass-Dark / Glass-Light) work.
+- For glass-aware surfaces use `backdrop-filter: var(--ican-backdrop-filter)` —
+  it no-ops on Dark/Light but frosts on glass themes.
+- `--ican-card-bg`, `--ican-primary-text`, `--ican-border`, `--ican-accent`,
+  `--ican-success`, `--ican-error`, `--ican-warning` cover ~90 % of widgets.
+
+Full variable reference and four-theme matrix:
+[`ICan-Widget-Theming-Guide.md`](./ICan-Widget-Theming-Guide.md).
+
+---
+
+## Common Tasks
+
+**Add a new ICan component to your widget:**
+```tsx
+import { Card, Button, StatCard } from 'ican/components';
+```
+
+**Register the widget so the portal picks it up:**
+```ts
+registerWidget({
+  id: 'your-widget-id',
+  widget: YourComponent,
+  configs: { layout: { w: 6, h: 5, minW: 4, minH: 4 } },
+});
+```
+
+**Read context provided by the portal (auth, theme, etc.):**
+```tsx
+const Widget: React.FC<{ icanContext?: IContextProvider }> = ({ icanContext }) => {
+  // icanContext.executeAction('Model', 'Query', {...}) etc.
+};
+```
+
+---
+
+## Troubleshooting
+
+| Symptom                                            | Likely cause                                                              |
+|----------------------------------------------------|---------------------------------------------------------------------------|
+| Widget loads in dev but not in portal              | Make sure you uploaded the **latest `dist/main.js`** + matching `bundle.json`. |
+| `style={{...}}` works in dev but not in portal     | Should never happen now — file an issue if it does.                       |
+| Hardcoded colors look wrong in another theme       | Replace with `var(--ican-*)` per the theming guide.                       |
+| TypeScript errors importing from `ican/components` | Run `npm install` to refresh — types come from `ican.d.ts`.               |
+
+---
+
+## Need help?
+
+Re-run `npx infaira-canvas init` to scaffold a fresh widget, or read the docs
+linked above. Both MDs are also bundled with every freshly initialised widget.

package/templates/designer.d.ts

@@ -0,0 +1,468 @@
+declare module "widget-designer/components" {
+
+
+    export type IWidgetMode = 'preview' | 'live' | 'thumbnail';
+    export type PropertyPanelType = 'general' | 'properties' | 'fields' | 'templates';
+
+    export interface IWidgetProps {
+        description?: string;
+        name?: string;
+        height?: number;
+    }
+
+
+    export interface IWidgetTemplateProps<T = any> {
+        icanContext?: IContextProvider;
+        designer: IWDDesignModeProps;
+        uiProps?: T;
+        initialSource: string;
+        updateWidgetHeight?: (height: number) => void
+    }
+    export type TemplateRenderer = (props: IWidgetTemplateProps) => JSX.Element;
+    export interface ILayoutProps {
+        w?: number,
+        h?: number,
+        minW?: number,
+        minH?: number,
+        maxH?: number,
+        maxW?: number
+    }
+    export type TargetDataStructure = 'value' | 'dictionary' | 'value-array' | 'dictionary-array';
+
+    export interface IWidgetTemplate {
+        template: TemplateRenderer;
+        toolbar?: TemplateRenderer;
+        id: string;
+        name: string,
+        description: string;
+        icon?: IconProp | JSX.Element,
+        canDragDropFields?: boolean,
+        layout?: ILayoutProps,
+        complexity?: 'easy' | 'medium' | 'hard' | 'advanced',
+        preLoader?: IWidgetPreloader,
+        expectedSchema?: TargetDataStructure,
+        autoHieght?: boolean,
+        getHeight?: () => number,
+        defaultProps?: any,
+        key?: string // for user templates
+        isTemplate?: boolean,
+        moduleId?: string
+    }
+    export type IUIPropertyDefinitionMap = {
+        [key: string]: (
+            IUIPropertyDefinition<IBaseProperty>
+            | { [subKey: string]: IUIPropertyDefinition<IBaseProperty> }
+        )
+    };
+
+    export type SourceBrowser = (icanContext: IContextProvider, template: IWidgetTemplate, onCancel: () => void, onSelected: (source: IModelPreview | IActionPreview) => Promise<boolean>) => React.ReactElement;
+
+    export interface IErrorProps {
+        id: string,
+        error: string,
+        type: 'property' | 'general',
+        containerId?: string,
+        fieldId?: string,
+        fieldClassName?: string,
+        highLightOnAdd?: boolean
+    }
+    export interface IWDDesignModeProps {
+        mode: IWidgetMode;
+        widgetName: string;
+        selectedPanel?: PropertyPanelType
+        onSelect: (ref: any, props: any, data: any, id?: string) => void;
+        selectedItem: any;
+        setUIProps: (uiProps: any) => void;
+        setWidgetProperties: (props: IWidgetProps) => void;
+        sourceBrowser: SourceBrowser;
+        addErrors: (errors: IErrorProps[]) => void
+        removeErrors: (ids: string[]) => void
+        removeAllErrors: () => void
+    }
+
+
+    export type PropertyPath = string | number | Array<string | number>;
+
+
+    export interface IBaseProperty {
+    }
+
+    export interface IPropertyEditorProps<T> {
+        uiProps: T;
+        onChange: (newProps: T) => void;
+        onChangeAny: (path: PropertyPath, value: any) => void;
+        icanContext: IContextProvider,
+        data?: any
+        parentUIProps: any;
+        designer: IWDDesignModeProps;
+    }
+
+    export interface IUIPropertyDefinition<T> {
+        defaults: T;
+        render: (props: IPropertyEditorProps<T>, icanContext?: IContextProvider, data?: any, containerId?: string) => JSX.Element;
+    }
+    export interface ISelectableItemUIProp {
+        id: PropertyPath;
+        value: IBaseProperty;
+        definition: IUIPropertyDefinition<IBaseProperty>; //IUIPropertyDefinition<any?> ?
+    }
+
+    export interface ISelectableItemProps {
+        designer: IWDDesignModeProps;
+        props: ISelectableItemUIProp[];
+        style?: React.CSSProperties;
+        onChange?: (props: any) => void;
+        data?: any;
+        className?: string;
+        showAtRuntime?: boolean;
+        elementId?: string;
+        preventLosingFocusOnNextClick?: boolean;
+    }
+    export const SelectableItem: React.FunctionComponent<ISelectableItemProps>
+
+    export function SimpleTextProperty(title: string, props: string, showCategoryTitle?: boolean): IUIPropertyDefinition<string>
+
+    export function selectUIProps(props: any, propDefs: any, ...keys: string[]): ISelectableItemUIProp[]
+
+
+    export interface IWDFilterPanelProps {
+        designer: IWDDesignModeProps,
+        icanContext: IContextProvider,
+        uiProps?: any,
+        containerRef: React.MutableRefObject<any>
+        data: { [key: string]: any }
+        onChangeFilters: (data: any) => void,
+        onClearFilters: () => void,
+        onOpenPanel?: () => void,
+        onClosePanel?: () => void
+    }
+    export const WidgetDesignerFilterPanel: React.FunctionComponent<IWDFilterPanelProps>
+
+    export interface IWidgetWrapperWithSidebarProps {
+        className: string;
+        designer?: IWDDesignModeProps;
+        data: any;
+        uiProps: any;
+        propDef: IUIPropertyDefinitionMap;
+        defaultTitle?: string;
+        elementId?: string;
+        filterSection?: () => React.ReactElement;
+        containerRef?: any;
+    }
+    export const WidgetWrapperWithTitleBar: React.FunctionComponent<IWidgetWrapperWithSidebarProps>
+
+
+    export interface ISerializedUIField {
+        id: string
+        name: string
+        type: string;
+        props: any;
+        isInputField?: boolean,
+        metaType?: TCollectionAttributeMetaTypeName
+    }
+
+    export interface IUseDropArgs {
+        /**
+         * designer props
+         */
+        designer?: IWDDesignModeProps,
+        /**
+         * ui props from the widget
+         */
+        uiProps: any,
+        /**
+         * path for the dropable fields (in uiProps)
+         */
+        propPath?: PropertyPath,
+        /**
+         * callback on props change
+         */
+        onChangeFields?: (newFields: ISerializedUIField[]) => void,
+        /**
+         * all the data from data sources , form fields and filters and etc. 
+         * sample structure 
+         * {
+         *      // if the widget has form fields 
+         *      form: {
+         *          input1: value1,
+         *          input2: value2,
+         *          input3: value3,
+         *      },
+         *      // if the widget has a filter panel 
+         *      filters: {
+         *          input1: value1,
+         *          input2: value2,
+         *      },
+         *      // data from data sources 
+         *      data: {
+         *          source1: <data from the source>
+         *      }
+         * }
+         */
+        data?: { [key: string]: any }
+        /**
+         * key of the data
+         * default is `form`
+         * 
+         * this will be used to get and set data 
+         */
+        dataKey?: string
+        /**
+         * call back when the data is changed
+         */
+        onChangeData?: (data: { [key: string]: any }) => void,
+        /**
+         * ican context
+         */
+        icanContext: IContextProvider,
+        disabled?: boolean
+    }
+
+    export interface IFieldContainerProps extends IUseDropArgs { }
+    export const FieldContainer: React.FunctionComponent<IFieldContainerProps>
+
+    export interface IRedirectUrl {
+        url: string,
+        target?: string
+    }
+
+    interface IWidgetProps {
+        id: string,
+        key: string,
+        isTemplate: boolean,
+        sourceUrl: string
+        templateType?: string,
+        templateKey?: string
+        templateId?: string,
+    }
+    export interface IRedirectWidget {
+        widget: IWidgetProps,
+        params?: { [key: string]: any }
+    }
+
+    export interface ILucyAction {
+        modelName: string;
+        action: string;
+        disableParamters?: boolean,
+        params: { [key: string]: any };
+        dialogTitle?: string,
+        executionMsg?: string,
+        postExecution?: {
+            success?: {
+                msg?: string,
+                action?: IAction,
+                goToHome?: boolean,
+                buttonTitle?: string,
+                reloadWidget?: boolean
+            },
+            error?: {
+                msg?: string,
+                action?: IAction,
+                goToHome?: boolean,
+                buttonTitle?: string,
+                reloadWidget?: boolean
+
+            }
+        }
+    }
+
+    export type IActionType = 'open-url' | 'open-widget' | 'execute-action'
+    export interface IAction {
+        type: IActionType,
+        redirectUrl?: IRedirectUrl
+        redirectWidget?: IRedirectWidget;
+        lucyAction?: ILucyAction
+    }
+    export interface IActionButtonProps {
+        designer?: any
+        icanContext: IContextProvider
+        title: string,
+        action: IAction,
+        styles?: React.CSSProperties
+        icon?: string,
+        iconPosition?: 'left' | 'right'
+        iconStyles?: React.CSSProperties,
+        data?: any;
+        customParams?: any;
+        onReloadWidget: () => void;
+    }
+    export const ActionButton: React.FunctionComponent<IActionButtonProps>
+
+    export interface IActionRenderComponentProps {
+        designer: IWDDesignModeProps
+        icanContext: IContextProvider
+        action: IAction
+        data: any,
+        onClose: () => void,
+        onReloadWidget: () => void,
+        customParams?: any,
+    }
+
+    export const ActionRenderComponent: React.FC<IActionRenderComponentProps>
+
+    export function AutoCompleteTextProperty(title: string, props: string, options: () => string[]): IUIPropertyDefinition<string>
+    export function ActionProperty(title: string, props: IAction): IUIPropertyDefinition<IAction>
+    export type BoolObject = { [key: string]: boolean };
+    export function BooleanGroupProperty(title: string, props: BoolObject, labels: any): IUIPropertyDefinition<BoolObject>
+    export function BooleanProperty(title: string, props?: boolean, showCategoryTitle?: boolean): IUIPropertyDefinition<boolean>
+
+    export interface IButtonPropertyProps extends IBaseProperty {
+        label: string,
+        onClick: IAction,
+        color?: string,
+        backgroundColor?: string,
+        icon?: {
+            icon: string
+            position?: 'left' | 'right',
+            color?: string,
+            size?: string
+        }
+    }
+
+    export interface IActionEditorLinkSettings {
+        disableUrl?: boolean;
+        disableWidget?: boolean;
+        disableAction?: boolean;
+        disableActionParameters?: boolean;
+    }
+    export function ButtonProperty(props: IButtonPropertyProps, title?: string, actionEditorSettings?: IActionEditorLinkSettings): IUIPropertyDefinition<IButtonPropertyProps>
+
+    export interface IColorProperty extends IBaseProperty {
+        color: string;
+    }
+    export function ColorProperty(title: string, props: IColorProperty): IUIPropertyDefinition<IColorProperty>
+    export interface IBackgroundProps {
+        image?: {
+            image: string,
+            position?: string,
+            size?: string,
+        },
+        color?: string
+    }
+
+    export interface ITextProps {
+        color?: string,
+        fontSize?: string,
+        align?: string,
+    }
+    export interface IContainerPropertyProps extends IBaseProperty {
+        background?: IBackgroundProps
+        text?: ITextProps
+        onClick?: IAction
+        removeShadow?: boolean
+    }
+    export function ContainerProperty(defaultProps: IContainerPropertyProps, title?: string): IUIPropertyDefinition<IContainerPropertyProps>
+
+    export interface IDataSourceParameter {
+        type: string;
+        id: string;
+        description: string;
+        example: string;
+        value: string;
+    }
+
+    export interface IDataSource {
+        id: string;
+        model: string;
+        action: string;
+        parameters: IDataSourceParameter[];
+        description: string;
+        icon?: string;
+        schema?: any;
+        type: 'model-action' | 'custom-json' | 'model-collection' | 'external-database',
+        json?: any // custom json
+        name?: string // source name - used for custom json and queries(in future) 
+        grouping?: any[]
+        filter?: any
+        modelKey?: string,
+        databaseId?: string
+    }
+    export interface IDataSourceBinding {
+        source: string;
+        path: string;
+    }
+
+    export function DataSourceProperty(title: string, source: IDataSourceBinding, sources: IDataSource[], context: IContextProvider, designer: IWDDesignModeProps, target: TargetDataStructure): IUIPropertyDefinition<IDataSourceBinding>
+
+    export interface IOptions {
+        showCategoryTitle?: boolean
+        data: Array<{ id: string, name: string }>,
+        selected?: string
+    }
+    export const DropdownProperty: (title: string, props: string, options: IOptions) => IUIPropertyDefinition<string>
+
+    export function HTMLCodeProperty(title: string, defaultProps: string): IUIPropertyDefinition<string>
+
+    export interface IIconProperty extends IBaseProperty {
+        icon: string,
+        color?: string
+        size?: string,
+    }
+    export function IconProperty(props: IIconProperty, title?: string): IUIPropertyDefinition<IIconProperty>
+
+    export function ModelProperty(title: string, source: string, sources: IDataSource[], context: IContextProvider, structure?: TargetDataStructure): IUIPropertyDefinition<string>
+
+    export function MultipleImagesProperty(title: string, props: string[], showCategoryTitle?: boolean): IUIPropertyDefinition<string[]>
+    export function RichTextProperty(title: string, props: string, showCategoryTitle?: boolean): IUIPropertyDefinition<string>
+    export function SimpleDateProperty(title: string, props: Date, showCategoryTitle?: boolean): IUIPropertyDefinition<Date>
+    export function SimpleNumberProperty(title: string, props: number): IUIPropertyDefinition<number>
+
+    export interface ITextFieldProperty extends IBaseProperty {
+        text: string;
+        fontSize: string;
+        textColor: string;
+        backgroundColor: string;
+    }
+
+    export interface ITextFieldPropertySettings {
+        isTextHidden?: boolean,
+        isBackgroundColorHidden?: boolean,
+        isFontSizeHidden?: boolean,
+        isTextColorVisible?: boolean,
+        useCustomColorPicker: boolean,
+    }
+
+    export function TextFieldProperty(title: string, props: ITextFieldProperty, settings?: ITextFieldPropertySettings): IUIPropertyDefinition<ITextFieldProperty>
+
+    export interface ITextProperty extends IBaseProperty {
+        text?: string,
+        color?: string
+        size?: string,
+        align?: string
+    }
+    export function TextProperty(defaultProps: ITextProperty, title?: string): IUIPropertyDefinition<ITextProperty>
+
+    export function VerticalAlignmentProperty(widgetProps: string): IUIPropertyDefinition<string>
+
+
+
+    export function extractContainerProperties(props: IContainerPropertyProps): {
+        styles: React.CSSProperties;
+        onClick: IAction;
+    }
+
+    export function extractTextProperties(props: ITextProperty, defaultText?: string): {
+        text: string;
+        styles: React.CSSProperties;
+    }
+
+    export function hasValue(value: any, allowZero?: boolean, allowNegative?: boolean): boolean
+    export function tryParseJSON(x: string, def?: any): any
+    export function generateUUID(): string
+
+    export type DebounceFunction = (...args: any[]) => void;
+    export type DebounceOptions = {
+        isImmediate: boolean,
+    }
+    export function debounce<F extends DebounceFunction>(func: F, waitMilliseconds?: number, options?: DebounceOptions): F
+    export const getUrlFriendlyString: (string: string, removeSlashes?: boolean) => string
+    export function loadInitialData(props: IWidgetTemplateProps): {
+        isLoading: boolean;
+        initialData: any;
+    }
+    export function extractContextData(props: IWidgetTemplateProps, initialData: any, currentContextData: any): {
+        [key: string]: any;
+    }
+    export function formatNumber(n: number | string, decimals?: number): string
+
+}