@machinemetrics/mm-react-tools 5.2.4 → 5.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +68 -1
- package/dist/hooks.d.ts +2 -1
- package/dist/hooks.d.ts.map +1 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/mm-react-tools.es.js +2085 -2025
- package/dist/settings.d.ts +130 -0
- package/dist/settings.d.ts.map +1 -0
- package/dist/useMMAgent.d.ts +69 -0
- package/dist/useMMAgent.d.ts.map +1 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -53,7 +53,7 @@ ReactDOM.render(
|
|
|
53
53
|
>
|
|
54
54
|
<App />
|
|
55
55
|
</MMProvider>,
|
|
56
|
-
document.getElementById('root')
|
|
56
|
+
document.getElementById('root'),
|
|
57
57
|
);
|
|
58
58
|
```
|
|
59
59
|
|
|
@@ -121,10 +121,77 @@ const PrivatePage = () => {
|
|
|
121
121
|
export default PrivatePage;
|
|
122
122
|
```
|
|
123
123
|
|
|
124
|
+
### Widget Settings
|
|
125
|
+
|
|
126
|
+
`useMMAppSetting(name, config, stateTriggers)` declares a dashboard widget setting; the host draws the form and delivers the value as `useMMAppContext()[name]`. `config.type` is one of `input`, `select`, `radio`, `thresholds`, `custom` or `dateRange`, and the `MMAppSettingConfig` type lists the options each one takes. `validate` returns `true` or an error message.
|
|
127
|
+
|
|
128
|
+
A `dateRange` setting offers presets from `DATE_RANGE_PRESETS` (`DEFAULT_DATE_RANGE_PRESETS` when `options` is omitted). The host resolves the chosen preset with the company's time zone and shop-day start, keeps it current as shop days roll over, and delivers a `DateRangeValue`. It is `undefined` until the host sends it. The setting needs a host that supports it: a dashboard on the Dashboard and ui releases that add the type, and mmdev-cli 1.1.0 or later for the playground. Release an app that declares one only once those are available to its users.
|
|
129
|
+
|
|
130
|
+
```jsx
|
|
131
|
+
useMMAppSetting('range', {
|
|
132
|
+
type: 'dateRange',
|
|
133
|
+
label: 'Date range',
|
|
134
|
+
options: ['today', 'yesterday', 'last7Days'],
|
|
135
|
+
default: 'today',
|
|
136
|
+
acceptGlobalOverride: 'dateRange',
|
|
137
|
+
});
|
|
138
|
+
|
|
139
|
+
const { range } = useMMAppContext();
|
|
140
|
+
// { preset: 'today', start: '2026-03-10T11:00:00.000Z', end: '2026-03-11T11:00:00.000Z',
|
|
141
|
+
// startDay: '2026-03-10', endDay: '2026-03-10' }
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`start` and `end` are ISO instants on shop-day boundaries, with `end` exclusive. `startDay` and `endDay` are inclusive `yyyy-MM-dd` shop days. With `acceptGlobalOverride: 'dateRange'` the widget follows the dashboard's date filter. Avoid naming the setting `dateRange`, which collides with a native widget prop. `default` must be one of `options`; otherwise the host uses the first offered preset. With `acceptGlobalOverride`, a dashboard filter set to a custom range, or to a preset the setting doesn't offer, replaces the widget with "Not available for …". The names `src`, `id`, `type`, `title`, `filter` and `dateRangeSettings` are reserved and can't be used as setting names, and the host ignores date range settings named `__proto__`, `constructor` or `prototype`. A widget can have at most 20 date range settings. See the developer hub's [Date Range page](https://developers.machinemetrics.com/docs/build-apps/mm-react-tools/widget-settings/date-range-setting) for the full behavior.
|
|
145
|
+
|
|
124
146
|
## Client ID and Secret
|
|
125
147
|
|
|
126
148
|
Contact support@machinemetrics.com for a Client ID and Secret.
|
|
127
149
|
|
|
150
|
+
## Hand a prompt or context to Max
|
|
151
|
+
|
|
152
|
+
Inside `MMProvider`, `useMMAgent()` exposes `ask` and `report`:
|
|
153
|
+
|
|
154
|
+
```tsx
|
|
155
|
+
const agent = useMMAgent();
|
|
156
|
+
// The host forwards the active thread from Max's cml:current message.
|
|
157
|
+
const { threadId } = useMMAppContext() as { threadId?: string | null };
|
|
158
|
+
|
|
159
|
+
// Call directly from a user click or key press.
|
|
160
|
+
const result = agent.ask('Build a scrap log', { newConversation: true });
|
|
161
|
+
if (result.ok) {
|
|
162
|
+
// Navigate here if the app also needs to change pages.
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
// Background context does not require user activation.
|
|
166
|
+
if (threadId) {
|
|
167
|
+
agent.report('app.context', { threadId, summary: 'Scrap log selected' });
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
`ask` trims the prompt and accepts up to `ASK_MAX_LENGTH` (4000) characters.
|
|
172
|
+
It returns `{ ok: false, reason }` for `empty`, `too-long`, `not-embedded`, or
|
|
173
|
+
`no-user-action`. A successful result means the message was posted to the host;
|
|
174
|
+
the host independently checks the source zone and user activation. With
|
|
175
|
+
`newConversation: true`, the prompt requests a fresh conversation's first
|
|
176
|
+
message. Otherwise it requests a composer prefill in the open conversation.
|
|
177
|
+
Ask before navigating so the source frame still exists when the host receives it.
|
|
178
|
+
|
|
179
|
+
`report` accepts `app.error`, `app.event`, or `app.context`, plus a required
|
|
180
|
+
`AgentEventPayload` containing `threadId` from the host context populated by
|
|
181
|
+
`cml:current`. Wait for that thread before reporting; do not invent a thread ID.
|
|
182
|
+
It posts `agent:event` with a generated unique `id`, the kind and an ISO timestamp, returning
|
|
183
|
+
`false` outside an embedded app or when `payload.threadId` is missing, not a string, or blank (including whitespace-only). No message is sent in those cases. It does not send a user message. Today, reports
|
|
184
|
+
only reach Max from the `cml-renderer` zone. Payload `type` and `instanceId`
|
|
185
|
+
fields are discarded so they cannot override the transport envelope.
|
|
186
|
+
|
|
187
|
+
The library exports `AGENT_ASK` (`agent:ask`), `AGENT_ASK_CONSUMED`
|
|
188
|
+
(`agent:ask-consumed`), and `AGENT_ASK_SOURCES` for the shared protocol.
|
|
189
|
+
`AgentAskPayload` describes the app-to-host `{ prompt, newConversation? }`
|
|
190
|
+
request. `AgentHostPrompt` describes the host-forwarded `{ at, prompt, source }`
|
|
191
|
+
prompt. `AgentAskConsumedPayload` is `{ kind, at }`, where `kind` is
|
|
192
|
+
`newThreadPrompt` or `agentAsk`. Timestamps are numbers; the host remains
|
|
193
|
+
responsible for checking the source frame and user activation.
|
|
194
|
+
|
|
128
195
|
## License
|
|
129
196
|
|
|
130
197
|
MIT © [MachineMetrics](https://github.com/machinemetrics)
|
package/dist/hooks.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { CredentialPurpose } from './credentialStore';
|
|
2
2
|
import type { MMContextValue, MMRequestOptions } from './MMContext';
|
|
3
|
+
import type { MMAppSettingCallbacks, MMAppSettingConfigFor } from './settings';
|
|
3
4
|
export declare const useSearchParamsState: (searchParamName: any, defaultValue: any, deserialize?: (v: any) => any, serialize?: (v: any) => any) => any[];
|
|
4
5
|
export declare const useAsyncEffect: (delegate: any, stateTriggers: readonly unknown[], destroy: any) => Promise<void>;
|
|
5
6
|
export declare const useAsyncInterval: (delegate: any, delay: number | null | undefined, stateTriggers: readonly unknown[]) => void;
|
|
@@ -48,7 +49,7 @@ export declare const useMMAppContext: () => any;
|
|
|
48
49
|
export declare const useMMAppParams: () => any;
|
|
49
50
|
export declare const useMMAppCommands: () => any;
|
|
50
51
|
export declare const useMMAppInfo: (info: any, stateTriggers?: readonly unknown[]) => void;
|
|
51
|
-
export declare const useMMAppSetting: (name:
|
|
52
|
+
export declare const useMMAppSetting: <T extends string = string>(name: string, cfg: MMAppSettingCallbacks<T> & MMAppSettingConfigFor<T>, stateTriggers?: readonly unknown[]) => void;
|
|
52
53
|
export declare const useMMAppSetClaims: (func: any, stateTriggers?: readonly unknown[]) => void;
|
|
53
54
|
export declare const useMMAppCustomInputOpen: (func: any, stateTriggers?: readonly unknown[]) => void;
|
|
54
55
|
export declare const useMMAppCustomInputSave: (func: any, stateTriggers?: readonly unknown[]) => void;
|
package/dist/hooks.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAM3D,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;
|
|
1
|
+
{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAM3D,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE/E,eAAO,MAAM,oBAAoB,GAC/B,iBAAiB,GAAG,EACpB,cAAc,GAAG,EACjB,eAAe,GAAG,GAAG,QAAM,EAC3B,aAAa,GAAG,GAAG,QAAM,UAqB1B,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,UAAU,GAAG,EACb,eAAe,SAAS,OAAO,EAAE,EACjC,SAAS,GAAG,kBAmBb,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,UAAU,GAAG,EACb,OAAO,MAAM,GAAG,IAAI,YAAO,EAC3B,eAAe,SAAS,OAAO,EAAE,SAiClC,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,gBAAgB;IAC5D,4CAA4C;IAC5C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,GAAI,CAAC,GAAG,GAAG,EACnC,MAAM,MAAM,EACZ,UAAU,oBAAoB,GAAG,IAAI,EACrC,QAAQ,MAAM,GAAG,IAAI,KACpB,mBAAmB,CAAC,CAAC,CA+BvB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,OAAO,GAAG,EAAE,OAAO,GAAG;;;;CA6CxD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAI,2BAA2B,GAAG;;;;CAoG/D,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,OAAO,GAAG;;;;CAgC1C,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,eAAe,GAAG,YAuCzC,GAAG,sCAC6B,GAAG;;;;IA2C1C,CAAC;AAEF,eAAO,MAAM,SAAS,QAAO,cAI5B,CAAC;AAEF,kGAAkG;AAClG,eAAO,MAAM,aAAa,GAAI,SAAS,iBAAiB,KAAG,MAAM,GAAG,IAKnE,CAAC;AAEF,eAAO,MAAM,eAAe,WAI3B,CAAC;AAEF,eAAO,MAAM,cAAc,WAI1B,CAAC;AAEF,eAAO,MAAM,gBAAgB,WAI5B,CAAC;AAEF,eAAO,MAAM,YAAY,GACvB,MAAM,GAAG,EACT,gBAAe,SAAS,OAAO,EAAO,SAQvC,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EACvD,MAAM,MAAM,EACZ,KAAK,qBAAqB,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC,CAAC,CAAC,EACxD,gBAAe,SAAS,OAAO,EAAO,SAQvC,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,MAAM,GAAG,EACT,gBAAe,SAAS,OAAO,EAAO,SAWvC,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,MAAM,GAAG,EACT,gBAAe,SAAS,OAAO,EAAO,SAUvC,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,MAAM,GAAG,EACT,gBAAe,SAAS,OAAO,EAAO,SAUvC,CAAC;AAEF,eAAO,MAAM,wBAAwB,GACnC,MAAM,GAAG,EACT,gBAAe,SAAS,OAAO,EAAO,SAWvC,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,MAAM,GAAG,EACT,gBAAe,SAAS,OAAO,EAAO,SAUvC,CAAC;AAEF,eAAO,MAAM,uBAAuB,eAEnC,CAAC"}
|
package/dist/index.d.ts
CHANGED
|
@@ -3,9 +3,13 @@ import MMProvider from './MMProvider';
|
|
|
3
3
|
import { useEventStream } from './eventStream';
|
|
4
4
|
import Link from './Link';
|
|
5
5
|
import { CredentialError } from './credentialError';
|
|
6
|
+
import { DATE_RANGE_PRESETS, DEFAULT_DATE_RANGE_PRESETS } from './settings';
|
|
6
7
|
import { useAsyncEffect, useAsyncInterval, useApiRequest, useProductionQuery, useDowntimeQuery, useMMAuth, useCredential, useMMTemplates, useQuantityStream, useSearchParamsState, _useMMApolloLinkContext, useMMAppParams, useMMAppCommands, useMMAppContext, useMMAppInfo, useMMAppSetting, useMMAppCustomInputOpen, useMMAppCustomInputSave, useMMAppCustomInputLabel, useMMAppSetClaims, useMMAppModalSave } from './hooks';
|
|
7
|
-
export { _useMMApolloLinkContext, useMMAuth, useCredential, useMMAppParams, useMMAppCommands, useMMAppContext, useMMAppInfo, useMMAppSetting, useMMAppCustomInputOpen, useMMAppCustomInputSave, useMMAppCustomInputLabel, useMMAppSetClaims, useMMAppModalSave, useMMTemplates, PrivateLayout, useAsyncEffect, useAsyncInterval, useApiRequest, useProductionQuery, useDowntimeQuery, useQuantityStream, useSearchParamsState, MMProvider, Link, useEventStream, CredentialError, };
|
|
8
|
+
export { _useMMApolloLinkContext, useMMAuth, useCredential, useMMAppParams, useMMAppCommands, useMMAppContext, useMMAppInfo, useMMAppSetting, useMMAppCustomInputOpen, useMMAppCustomInputSave, useMMAppCustomInputLabel, useMMAppSetClaims, useMMAppModalSave, useMMTemplates, PrivateLayout, useAsyncEffect, useAsyncInterval, useApiRequest, useProductionQuery, useDowntimeQuery, useQuantityStream, useSearchParamsState, MMProvider, Link, useEventStream, CredentialError, DATE_RANGE_PRESETS, DEFAULT_DATE_RANGE_PRESETS, };
|
|
8
9
|
export type { MMContextValue, MMAuthResult, MMUrls, MMRequest, MMRequestOptions, } from './MMContext';
|
|
9
10
|
export type { MMProviderProps, MMReleaseStage } from './MMProvider';
|
|
10
11
|
export type { UseApiRequestOptions, UseApiRequestResult } from './hooks';
|
|
12
|
+
export type { DateRangePreset, DateRangeValue, MMAppSettingConfig, MMAppDateRangeDeclaration, MMAppSettingOption, MMAppSettingOptions, MMAppSettingValidateResult, MMAppInputSetting, MMAppSelectSetting, MMAppRadioSetting, MMAppThresholdsSetting, MMAppThresholdField, MMAppCustomSetting, MMAppDateRangeSetting, MMAppSettingCallbacks, MMAppSettingConfigFor, MMAppLooseSetting, } from './settings';
|
|
13
|
+
export { useMMAgent, ASK_MAX_LENGTH, AGENT_ASK, AGENT_ASK_CONSUMED, AGENT_ASK_SOURCES, } from './useMMAgent';
|
|
14
|
+
export type { AgentEventKind, AgentEvent, AgentEventPayload, AgentAskPayload, AgentHostPrompt, AgentAskConsumedPayload, AskOptions, AskResult, MMAgent, } from './useMMAgent';
|
|
11
15
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,iBAAiB,CAAC;AAC5C,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,IAAI,MAAM,QAAQ,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,uBAAuB,EACvB,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,cAAc,EACd,eAAe,
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,iBAAiB,CAAC;AAC5C,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,IAAI,MAAM,QAAQ,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,uBAAuB,EACvB,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,CAAC;AAEF,YAAY,EACV,cAAc,EACd,YAAY,EACZ,MAAM,EACN,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACzE,YAAY,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,cAAc,EACd,SAAS,EACT,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,SAAS,EACT,OAAO,GACR,MAAM,cAAc,CAAC"}
|