@ttoss/geovis-workspace 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, Terezinha Tech Operations (ttoss)
+
+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,154 @@
+# @ttoss/geovis-workspace
+
+A React component that composes a sidebar-driven workspace around a GeoVis map.
+The sidebars are configured through a `config` object and the map is rendered
+from a GeoVis `visualizationSpec`; each sidebar only renders when defined.
+
+## Installation
+
+```bash
+pnpm add @ttoss/geovis-workspace
+```
+
+`@ttoss/geovis`, `@ttoss/ui`, `@ttoss/react-i18n` and `react` are peer
+dependencies.
+
+## Storybook
+
+Interactive examples are available on [Storybook](https://storybook.ttoss.dev/).
+
+## Usage
+
+The parent owns the selection state and derives the next `visualizationSpec`
+from it, so picking a menu item recolors the map. Seed the initial selection
+with `getInitialSelection` (reads each menu's `defaultValue`).
+
+```tsx
+import { type VisualizationSpec } from '@ttoss/geovis';
+import {
+  type GeovisWorkspaceConfig,
+  GeovisWorkspace,
+  getInitialSelection,
+} from '@ttoss/geovis-workspace';
+import * as React from 'react';
+
+const config: GeovisWorkspaceConfig = {
+  leftSidebar: {
+    menus: [
+      {
+        id: 'variable',
+        title: 'Variável',
+        defaultValue: 'rate',
+        items: [
+          { value: 'rate', label: 'Taxa cumulativa' },
+          { value: 'range', label: 'Faixa (% da pop 65+)' },
+        ],
+      },
+    ],
+  },
+  rightSidebar: { title: 'Details' },
+};
+
+// Maps the current selection to a GeoVis spec — your domain logic.
+const buildSpec = (
+  selection: Record<string, string | undefined>
+): VisualizationSpec => {
+  // ...
+};
+
+export const Example = () => {
+  const [selection, setSelection] = React.useState(() => {
+    return getInitialSelection({ config });
+  });
+
+  const visualizationSpec = React.useMemo(() => {
+    return buildSpec(selection);
+  }, [selection]);
+
+  return (
+    <GeovisWorkspace
+      config={config}
+      visualizationSpec={visualizationSpec}
+      variables={selection}
+      onVariableChange={setSelection}
+    />
+  );
+};
+```
+
+`variables` and `onVariableChange` are optional: omit both to let the workspace
+manage the selection internally (seeded from `defaultValue`). Provide them to
+control it from the parent — required when the selection must drive the
+`visualizationSpec`. Selection is per menu group: choosing an item only affects
+its own group. Read the current selection anywhere inside the workspace with
+`useGeovisWorkspace()`.
+
+## API
+
+### `GeovisWorkspace` props
+
+| Prop                | Type                                  | Description                                                 |
+| ------------------- | ------------------------------------- | ----------------------------------------------------------- |
+| `config`            | `GeovisWorkspaceConfig`               | Describes the sidebars. Required.                           |
+| `visualizationSpec` | `VisualizationSpec`                   | GeoVis spec rendered in the main map area. Required.        |
+| `variables`         | `Record<string, string \| undefined>` | Controlled selection per menu group. Omit for uncontrolled. |
+| `onVariableChange`  | `(variables) => void`                 | Called with the full next selection when an item is picked. |
+
+### `GeovisWorkspaceConfig`
+
+| Property       | Type                               | Description                            |
+| -------------- | ---------------------------------- | -------------------------------------- |
+| `leftSidebar`  | `{ menus: GeovisWorkspaceMenu[] }` | Left sidebar config. Omit to hide it.  |
+| `rightSidebar` | `GeovisWorkspaceRightSidebar`      | Right sidebar config. Omit to hide it. |
+
+### `GeovisWorkspaceMenu`
+
+| Property       | Type                                 | Description                            |
+| -------------- | ------------------------------------ | -------------------------------------- |
+| `id`           | `string`                             | Unique group identifier.               |
+| `title`        | `string`                             | Title shown above the group.           |
+| `items`        | `{ value: string; label: string }[]` | Selectable items.                      |
+| `defaultValue` | `string`                             | Item selected by default in the group. |
+
+### `GeovisWorkspaceRightSidebar`
+
+| Property          | Type                             | Description                            |
+| ----------------- | -------------------------------- | -------------------------------------- |
+| `title`           | `string`                         | Title shown at the top of the sidebar. |
+| `legendWithColor` | `GeovisWorkspaceLegendWithColor` | Color-legend panel. Omit to hide it.   |
+
+### `GeovisWorkspaceLegendWithColor`
+
+A declarative color-legend panel: a description, a swatch-per-class legend and a
+list of (optionally linked) data sources. Each block renders only when present.
+
+| Property      | Type                                            | Description                       |
+| ------------- | ----------------------------------------------- | --------------------------------- |
+| `description` | `string`                                        | Paragraph under the title.        |
+| `legend`      | `{ title?: string; items: { color; label }[] }` | Class swatches (color + label).   |
+| `sources`     | `{ title?: string; items: { label; href? }[] }` | Data sources; `href` adds a link. |
+
+```tsx
+const config: GeovisWorkspaceConfig = {
+  rightSidebar: {
+    title: 'POPULAÇÃO 65+ COMO % DA POPULAÇÃO TOTAL',
+    legendWithColor: {
+      description: 'Proporção da população total com 65 anos ou mais.',
+      legend: {
+        title: 'Classes',
+        items: [
+          { color: '#eff3ff', label: '0% – 5%' },
+          { color: '#08519c', label: '20% – 100%' },
+        ],
+      },
+      sources: {
+        title: 'Fonte dos dados:',
+        items: [
+          { label: 'SEADE (2025)', href: 'https://repositorio.seade.gov.br' },
+          { label: 'Geometria: Distritos Municipais de São Paulo.' },
+        ],
+      },
+    },
+  },
+};
+```