panelui-web 0.0.0-stage → 0.1.0

package/dist/components/planet/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Planet — the world as dots on a globe you can turn, with things pinned to it.
+ *
+ * ```tsx
+ * <Planet defaultRotation={[78, 18]}>
+ *   <Planet.Globe>
+ *     <Planet.Marker lat={24.7} lng={46.7} label="Saudi Arabia" count={2} />
+ *     <Planet.Marker lat={-33.9} lng={151.2} label="Australia" />
+ *   </Planet.Globe>
+ *   <Planet.Controls />
+ * </Planet>
+ * ```
+ *
+ * ## Two layers
+ *
+ * The globe is a canvas and the markers are ordinary elements laid over it.
+ * The land is several thousand dots, which is a job for a canvas; a marker is
+ * a label, an avatar, maybe a link, which is a job for the DOM. Each frame the
+ * canvas is redrawn and every marker is moved to where its coordinate now is,
+ * by a transform written straight to the element. Turning the globe never
+ * re-renders React.
+ *
+ * ## Nothing is drawn that is not asked for
+ *
+ * There is no loop running while the globe is still. A drag, a press on a
+ * control, a resize or a change of theme asks for one frame, and a frame asks
+ * for another only while something is still moving.
+ *
+ * ## The land is a question, not a shape
+ *
+ * `land.ts` says, per square degree, whether it is land. A grid of points is
+ * laid over the sphere at an even spacing and the ones on land are kept, so
+ * the coastlines come out as the edge of a dot pattern. The spacing is in
+ * pixels, so a small globe and a large one are dotted equally finely and a
+ * small one is not a smear.
+ *
+ * ## It takes the text colour
+ *
+ * The dots and the shading are drawn in `currentColor`, read from the element
+ * each frame. On a dark surface the land is light and on a light one it is
+ * dark, with no colour passed in and nothing to keep in step with the theme.
+ */
+import { type ComponentProps, type MouseEvent, type ReactNode } from 'react';
+/** `[longitude, latitude]` of the point facing the viewer, in degrees. */
+export type PlanetRotation = [longitude: number, latitude: number];
+export interface PlanetHandle {
+    /** Turn by this many degrees of longitude, and optionally latitude. */
+    rotateBy(longitude: number, latitude?: number): void;
+    /** Turn until this coordinate faces the viewer. */
+    rotateTo(rotation: PlanetRotation): void;
+    /** The coordinate facing the viewer right now. */
+    getRotation(): PlanetRotation;
+}
+export interface PlanetProps extends Omit<ComponentProps<'div'>, 'children'> {
+    children?: ReactNode;
+    /**
+     * The coordinate facing the viewer to begin with, as `[longitude, latitude]`
+     * in degrees. Read once: turning the globe afterwards does not change it.
+     */
+    defaultRotation?: PlanetRotation;
+    /**
+     * Turn on its own, at this many degrees of longitude a second. `true` is 6.
+     * It stops while the pointer is over the globe, while it is being dragged,
+     * while it is off screen, and for anyone who has asked for reduced motion.
+     */
+    autoRotate?: boolean | number;
+    /** Let the globe be dragged and turned with the arrow keys. */
+    interactive?: boolean;
+    /** Called with the coordinate facing the viewer each time the globe comes to rest. */
+    onRotationChange?: (rotation: PlanetRotation) => void;
+}
+export interface PlanetGlobeProps extends Omit<ComponentProps<'div'>, 'children' | 'color'> {
+    /** The markers. Anything else placed here is laid over the globe unmoved. */
+    children?: ReactNode;
+    /** Which of the theme's roles the light round the globe is drawn in. */
+    color?: PlanetMarkerColor;
+    /** What a screen reader calls the globe. */
+    label?: string;
+}
+declare function PlanetGlobe({ children, className, color, label, ...props }: PlanetGlobeProps): import("react").JSX.Element;
+declare namespace PlanetGlobe {
+    var displayName: string;
+}
+/** Which of the theme's roles a marker's dot is drawn in. */
+export type PlanetMarkerColor = 'primary' | 'info' | 'success' | 'warning' | 'destructive';
+export interface PlanetMarkerProps extends Omit<ComponentProps<'div'>, 'children' | 'color' | 'onClick'> {
+    /** Degrees north of the equator. South is negative. */
+    lat: number;
+    /** Degrees east of Greenwich. West is negative. */
+    lng: number;
+    /** A caption in a tag above the pin. */
+    label?: ReactNode;
+    /** A figure after the label, in a quieter colour. */
+    count?: ReactNode;
+    /** Which of the theme's roles the dot, or the ring of a pin with children, is drawn in. */
+    color?: PlanetMarkerColor;
+    /** Spreads a fading ring from the marker, for one that wants looking at. */
+    pulse?: boolean;
+    /**
+     * Called when the marker is pressed. Passing this makes the marker a
+     * button: it takes focus, and Enter or Space press it.
+     */
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /** Draws the marker as the one that has been picked. */
+    selected?: boolean;
+    /** What a screen reader calls a marker that can be pressed. Defaults to its label. */
+    name?: string;
+    /** Extra classes for the label. */
+    labelClassName?: string;
+    /** What is drawn at the coordinate: an avatar, an icon. A dot when left out. */
+    children?: ReactNode;
+}
+declare function PlanetMarker({ lat, lng, label, count, color, pulse, onClick, selected, name, className, labelClassName, children, ...props }: PlanetMarkerProps): import("react").JSX.Element;
+declare namespace PlanetMarker {
+    var displayName: string;
+}
+export interface PlanetControlsProps extends Omit<ComponentProps<'div'>, 'children'> {
+    /** Degrees of longitude one press turns the globe. */
+    step?: number;
+    /** Words to show between the two arrows. Without them it is the arrows alone. */
+    children?: ReactNode;
+}
+declare function PlanetControls({ step, className, children, ...props }: PlanetControlsProps): import("react").JSX.Element;
+declare namespace PlanetControls {
+    var displayName: string;
+}
+export declare const Planet: import("react").ForwardRefExoticComponent<Omit<PlanetProps, "ref"> & import("react").RefAttributes<PlanetHandle>> & {
+    Globe: typeof PlanetGlobe;
+    Marker: typeof PlanetMarker;
+    Controls: typeof PlanetControls;
+};
+export { PlanetGlobe, PlanetMarker, PlanetControls };