# LogScale

Import `LogScale` and `useLogScale` from `@pibbl/core/viz`. Equal ratios map to
equal distances. There is no generic scale-family selector.

```tsx
import { LogScale, Axis } from "@pibbl/core/viz";
<LogScale id="mass" domain={[1, 1000]} range="width" base={10}>
  <Axis scale="mass" position="bottom" />
</LogScale>;
```

## Provider signature and defaults

`LogScale(props: LogScaleProps): PibblNode` provides a named mapping to descendants.

| Input      | Default  | Contract                                                        |
| ---------- | -------- | --------------------------------------------------------------- |
| `id`       | required | Nonempty string or symbol                                       |
| `domain`   | required | Two distinct finite positive endpoints, ascending or descending |
| `range`    | required | `"width"`, `"height"`, or two finite numeric endpoints          |
| `reverse`  | `false`  | Reverses the range, independently of domain direction           |
| `base`     | `10`     | Finite number greater than 1; controls power ticks, not mapping |
| `style`    | omitted  | Existing scale layout style; layout ownership remains explicit  |
| `children` | omitted  | Ordinary Pibbl nodes                                            |

Domain, range, reverse, base, whole style, and declared style fields accept the
same signals as other scale providers. Changing base publishes a new snapshot
even when the mapping stays equal. The provider responds to its containing
allocation. No nicening or clamping is automatic.

## Hook and fixed return contract

`useLogScale(id: ScaleId): Signal<ResolvedLogScale>` returns one stable shared
readonly signal per provider. `.get()` reads the current frozen snapshot.
Missing IDs fail; reading a mismatched family throws `TypeError`. Signal reads
track the caller normally; the provider owns cleanup when unmounted.

The snapshot exposes `type: "log"`, frozen original `domain`, resolved `range`,
`frame`, `base`, and these methods:

- `map(value: number): number`: finite positive input to logical pixels. Positive
  out-of-domain values extrapolate. Zero and negative values are errors.
- `invert(pixel: number): number`: finite logical pixels to positive numeric
  values. Range endpoints return the exact original domain endpoints.
- `ticks(count = 5): readonly number[]`: frozen, ordered, bounded ticks.
  Count must be an integer 2–100. Both original endpoints are always included.
  Interior ticks are integer powers of `base`, subsampled by an integer exponent
  stride to fit the count. Two requests return only endpoints; intervals with
  no interior powers also return endpoints. Tick count is a maximum, not a
  promise of an exact number. Ticks never change mapping or domain.

A collapsed range maps all values to its single pixel but cannot be inverted.
A collapsed domain, nonpositive/nonfinite domain or map value, invalid base,
nonfinite span/output, invalid count, or unrepresentable tick exponent throws
`RangeError`. Extremely close endpoints whose logarithms become equal reject.
Inversion that overflows or underflows to zero rejects. Invalid reverse uses the
shared scale validation (`TypeError`). Malformed endpoints/ranges reject instead
of being coerced. A base very close to one may map normally but reject tick
requests whose integer exponents exceed numeric precision; use a larger base.

## Composition and inspection

Axes, `LineSeries`, `PointSeries`, `PlotSeries`, `ScaleAdjust`, `HoverData`,
`nearestPoint`, and `nearestDomainValue` accept this continuous mapping. Numeric
inspection measures distances after mapping. Missing/nonfinite samples retain
existing mark/query behavior; zero/negative log coordinates reject unless the
caller excludes them with `defined`. Value bars need an explicit positive
baseline or positive ranges; their default zero baseline is invalid on a log
scale. A log chart has no zero position.

Labels remain independent: use `Axis.labelOverlap="skip"` for crowded endpoints
and `formatNumber` for units. Never interpret a logarithmic bar length as an
additive magnitude. The NASA example uses equal-size dots instead.

## Runnable examples

The [minimal log demo](/playground/#/examples/composition/viz-log-basics) demonstrates the
provider, hook, mapping, inverse, and ticks. The
[NASA mass chart](/playground/#/examples/composition/viz-log-masses) compares checked-in
planetary data across orders of magnitude with touch/keyboard inspection.

## API details from source

<span id="api-LogScale"></span>

### LogScale

Provides a named positive logarithmic mapping to descendant marks and axes.

```ts
LogScale: (props: LogScaleProps) => PibblNode
```

Related API: [LogScale](/reference/components/log-scale/), [LogScaleProps](/reference/components/log-scale/), [PibblNode](/reference/types/elements-components/#pibblnode).

#### Parameters

- **`props`** — Identity, positive domain, range, and optional tick base. See [LogScaleProps](/reference/components/log-scale/).

#### Returns

Descendant content within the logarithmic scale scope.

[View source — packages/core/src/features/viz/lib/log-scale-component.ts:10](/source/packages/core/src/features/viz/lib/log-scale-component-ts/#L10)

<span id="api-useLogScale"></span>

### useLogScale

Reads an ancestor logarithmic scale as a stable shared readonly signal.

```ts
useLogScale: (id: ScaleId) => Signal<ResolvedLogScale>
```

Related API: [useLogScale](/reference/components/log-scale/), [ScaleId](/reference/components/scale/), [Signal](/reference/types/canvas-runtime/#signal), [ResolvedLogScale](/reference/components/log-scale/).

#### Parameters

- **`id`** — Ancestor scale identity. See [ScaleId](/reference/components/scale/).

#### Returns

The reactive logarithmic mapping. See [ResolvedLogScale](/reference/components/log-scale/).

[View source — packages/core/src/features/viz/lib/use-log-scale.ts:10](/source/packages/core/src/features/viz/lib/use-log-scale-ts/#L10)

<span id="api-LogScaleProps"></span>

### LogScaleProps

Positive logarithmic provider inputs. See LinearScaleProps.

```ts
interface LogScaleProps extends LinearScaleProps
```

Related API: [LogScaleProps](/reference/components/log-scale/), [LinearScaleProps](/reference/components/scale/).

[View source — packages/core/src/features/viz/lib/types.ts:244](/source/packages/core/src/features/viz/lib/types-ts/#L244)

#### Properties and methods

<span id="api-LogScaleProps-base"></span>
<details>
<summary>base (optional)</summary>


```ts
readonly base?: SignalValue<number> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Base for power ticks; finite and greater than one, default 10. Mapping is base-independent.

[View source — packages/core/src/features/viz/lib/types.ts:246](/source/packages/core/src/features/viz/lib/types-ts/#L246)

</details>

<span id="api-LogScaleProps-id"></span>
<details>
<summary>id</summary>


```ts
readonly id: ScaleId
```

Related API: [ScaleId](/reference/components/scale/).

Stable identifier of this resource or connection. See ScaleId.

[View source — packages/core/src/features/viz/lib/types.ts:75](/source/packages/core/src/features/viz/lib/types-ts/#L75)

</details>

<span id="api-LogScaleProps-domain"></span>
<details>
<summary>domain</summary>


```ts
readonly domain: SignalValue<LinearDomain>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [LinearDomain](/reference/components/scale/).

Data values or endpoints accepted by the scale. See SignalValue, LinearDomain
.

[View source — packages/core/src/features/viz/lib/types.ts:80](/source/packages/core/src/features/viz/lib/types-ts/#L80)

</details>

<span id="api-LogScaleProps-range"></span>
<details>
<summary>range</summary>


```ts
readonly range: SignalValue<ScaleRange>
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [ScaleRange](/reference/components/scale/).

Logical output coordinates produced by the scale. See SignalValue, ScaleRange
.

[View source — packages/core/src/features/viz/lib/types.ts:85](/source/packages/core/src/features/viz/lib/types-ts/#L85)

</details>

<span id="api-LogScaleProps-reverse"></span>
<details>
<summary>reverse (optional)</summary>


```ts
readonly reverse?: SignalValue<boolean> | undefined
```

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue).

Whether to reverse the direction of the mapping or guide. See SignalValue.

[View source — packages/core/src/features/viz/lib/types.ts:87](/source/packages/core/src/features/viz/lib/types-ts/#L87)

</details>

<span id="api-LogScaleProps-style"></span>
<details>
<summary>style (optional)</summary>


<details>
<summary>Full type declaration</summary>

```ts
readonly style?: SignalValue<Readonly<{ left?: SignalValue<number | `${number}%` | undefined>; top?: SignalValue<number | `${number}%` | undefined>; width?: SignalValue<Length | undefined>; height?: SignalValue<Length | undefined>; alignSelf?: SignalValue<"auto" | "center" | "end" | "flex-end" | "flex-start" | "start" | "stretch" | undefined>; justifySelf?: SignalValue<"auto" | "center" | "end" | "start" | "stretch" | undefined>; flexBasis?: SignalValue<Length | undefined>; flexGrow?: SignalValue<number | undefined>; flexShrink?: SignalValue<number | undefined>; gridColumnStart?: SignalValue<number | undefined>; gridColumnSpan?: SignalValue<number | undefined>; gridRowStart?: SignalValue<number | undefined>; gridRowSpan?: SignalValue<number | undefined>; transition?: SignalValue<PibblTransitionBinding | undefined>; custom?: unknown; filter?: SignalValue<PibblFilter | readonly PibblFilter[] | undefined>; }>> | undefined
```

</details>

Related API: [SignalValue](/reference/types/signal-inputs/#signalvalue), [Length](/reference/types/layout/#length), [PibblTransitionBinding](/reference/hooks/use-visibility-transition/), [PibblFilter](/reference/types/filters/#pibblfilter).

Declared presentation and layout properties. See SignalValue, SignalStyle,
ScaleLayoutStyle.

[View source — packages/core/src/features/viz/lib/types.ts:92](/source/packages/core/src/features/viz/lib/types-ts/#L92)

</details>

<span id="api-LogScaleProps-children"></span>
<details>
<summary>children (optional)</summary>


```ts
readonly children?: PibblNode
```

Related API: [PibblNode](/reference/types/elements-components/#pibblnode).

Descendant content or the callback that supplies it. See PibblNode.

[View source — packages/core/src/features/viz/lib/types.ts:94](/source/packages/core/src/features/viz/lib/types-ts/#L94)

</details>

<span id="api-ResolvedLogScale"></span>

### ResolvedLogScale

Positive logarithmic mapping with numeric inverse. See ResolvedLinearScale.

```ts
interface ResolvedLogScale extends Omit<ResolvedLinearScale, "type">
```

Related API: [ResolvedLogScale](/reference/components/log-scale/), [ResolvedLinearScale](/reference/components/scale/).

[View source — packages/core/src/features/viz/lib/types.ts:249](/source/packages/core/src/features/viz/lib/types-ts/#L249)

#### Properties and methods

<span id="api-ResolvedLogScale-type"></span>
<details>
<summary>type</summary>


```ts
readonly type: "log"
```

Logarithmic mapping discriminant. See LogScaleProps.

[View source — packages/core/src/features/viz/lib/types.ts:251](/source/packages/core/src/features/viz/lib/types-ts/#L251)

</details>

<span id="api-ResolvedLogScale-base"></span>
<details>
<summary>base</summary>


```ts
readonly base: number
```

Resolved base used for power ticks. See LogScaleProps.

[View source — packages/core/src/features/viz/lib/types.ts:253](/source/packages/core/src/features/viz/lib/types-ts/#L253)

</details>

<span id="api-ResolvedLogScale-domain"></span>
<details>
<summary>domain</summary>


```ts
readonly domain: LinearDomain
```

Related API: [LinearDomain](/reference/components/scale/).

Data values or endpoints accepted by the scale. See LinearDomain.

[View source — packages/core/src/features/viz/lib/types.ts:193](/source/packages/core/src/features/viz/lib/types-ts/#L193)

</details>

<span id="api-ResolvedLogScale-range"></span>
<details>
<summary>range</summary>


```ts
readonly range: readonly [number, number]
```

Logical output coordinates produced by the scale. See ResolvedLinearScale.

[View source — packages/core/src/features/viz/lib/types.ts:195](/source/packages/core/src/features/viz/lib/types-ts/#L195)

</details>

<span id="api-ResolvedLogScale-frame"></span>
<details>
<summary>frame</summary>


```ts
readonly frame: Readonly<LayoutBox>
```

Related API: [LayoutBox](/reference/types/layout/#layoutbox).

Resolved layout frame containing the scale. See LayoutBox.

[View source — packages/core/src/features/viz/lib/types.ts:197](/source/packages/core/src/features/viz/lib/types-ts/#L197)

</details>

<span id="api-ResolvedLogScale-map"></span>
<details>
<summary>map</summary>


```ts
map: (value: number) => number
```

Maps a numeric domain value to a logical range coordinate. See ResolvedLinearScale.

##### Parameters

- **`value`** — Numeric domain coordinate.

##### Returns

The corresponding range coordinate.

[View source — packages/core/src/features/viz/lib/types.ts:203](/source/packages/core/src/features/viz/lib/types-ts/#L203)

</details>

<span id="api-ResolvedLogScale-invert"></span>
<details>
<summary>invert</summary>


```ts
invert: (pixel: number) => number
```

Related API: [invert](/reference/types/filters/#invert).

Maps a logical range coordinate back into the numeric domain. See ResolvedLinearScale
.

##### Parameters

- **`pixel`** — Coordinate in the scale's pixel range.

##### Returns

The corresponding numeric domain value.

[View source — packages/core/src/features/viz/lib/types.ts:210](/source/packages/core/src/features/viz/lib/types-ts/#L210)

</details>

<span id="api-ResolvedLogScale-ticks"></span>
<details>
<summary>ticks</summary>


```ts
ticks: (count?: number) => readonly number[]
```

Returns representative numeric tick values for the requested count. See
ResolvedLinearScale.

##### Parameters

- **`count`** — Suggested number of ticks.

##### Returns

Tick values in domain coordinates.

[View source — packages/core/src/features/viz/lib/types.ts:217](/source/packages/core/src/features/viz/lib/types-ts/#L217)

</details>

## Implementation guidance for agents

Read the [Data visualization companion](/agents/topics/visualization/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [File sizes across orders of magnitude](/minimal-examples/viz/log-scale/): Multiplying the size by ten moves the same distance. [Plain source](/minimal/viz/log-scale.tsx)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.