matterviz 0.3.6 → 0.4.0

package/dist/sanitize.js

@@ -0,0 +1,116 @@
+import DOMPurify from 'dompurify';
+import { format_formula_html } from './phase-diagram/utils';
+const SAFE_TAGS = [`a`, `b`, `i`, `em`, `strong`, `sub`, `sup`, `br`, `span`, `code`, `small`];
+const SAFE_ATTRS = [`style`, `class`, `title`, `href`, `target`, `rel`];
+// only allow safe CSS properties for text formatting
+const SAFE_STYLE_RE = /^\s*(color|font-weight|font-style|font-size|text-decoration|vertical-align)\s*:/;
+// Add a token to a space-separated string if not already present
+const ensure_token = (value, token) => {
+    const tokens = new Set(value.split(/\s+/).filter(Boolean));
+    tokens.add(token);
+    return [...tokens].join(` `);
+};
+// undefined = not yet checked, null = no DOM available, instance = ready
+let purify;
+function get_purify() {
+    if (purify !== undefined)
+        return purify;
+    if (typeof globalThis.window === `undefined`)
+        return (purify = null);
+    const instance = DOMPurify();
+    if (typeof instance.sanitize !== `function`) {
+        purify = null;
+        return null;
+    }
+    purify = instance;
+    instance.addHook(`uponSanitizeAttribute`, (node, data) => {
+        if (data.attrName === `style`) {
+            const rules = data.attrValue.split(`;`).filter((rule) => SAFE_STYLE_RE.test(rule));
+            if (rules.length === 0)
+                data.keepAttr = false;
+            else
+                data.attrValue = rules.join(`;`);
+        }
+        // force rel="noopener" on links to prevent window.opener attacks
+        if (data.attrName === `href`) {
+            node.setAttribute(`rel`, ensure_token(node.getAttribute(`rel`) ?? ``, `noopener`));
+        }
+        if (data.attrName === `rel`) {
+            data.attrValue = ensure_token(data.attrValue, `noopener`);
+        }
+    });
+    return instance;
+}
+// Wrap in <svg>, sanitize with allowlist, then unwrap. Required because DOMPurify
+// needs the <svg> parent to parse children in the SVG namespace.
+function sanitize_svg_content(html, allowed_tags, allowed_attrs) {
+    const dp = get_purify();
+    if (!dp)
+        return html;
+    const wrapped = dp.sanitize(`<svg>${html}</svg>`, {
+        ALLOWED_TAGS: [...allowed_tags, `svg`],
+        ALLOWED_ATTR: allowed_attrs,
+    });
+    const open_end = wrapped.indexOf(`>`);
+    const close_start = wrapped.lastIndexOf(`</svg>`);
+    if (open_end === -1 || close_start === -1)
+        return wrapped;
+    return wrapped.slice(open_end + 1, close_start);
+}
+const stringify_html_input = (html) => {
+    if (html == null)
+        return ``;
+    if (typeof html === `string`)
+        return html;
+    if (typeof html === `number`)
+        return Number.isNaN(html) ? `NaN` : `${html}`;
+    if (typeof html === `boolean` || typeof html === `bigint`)
+        return `${html}`;
+    if (typeof html !== `object`)
+        return ``;
+    try {
+        return JSON.stringify(html) ?? ``;
+    }
+    catch {
+        return ``;
+    }
+};
+// Sanitize HTML string, allowing only safe formatting tags and links.
+// Two-pass: happy-dom promotes dangerous children when a non-allowed parent is
+// stripped (e.g. <div><script>…</script></div> → <script>…</script>). The first
+// pass explicitly removes dangerous tags so they can't survive promotion.
+export function sanitize_html(html) {
+    const str = stringify_html_input(html);
+    const dp = get_purify();
+    if (!dp)
+        return str;
+    // oxfmt-ignore
+    const safe = dp.sanitize(str, { ADD_ATTR: [`target`], FORBID_TAGS: [
+            `script`, `style`, `iframe`, `object`, `embed`, `form`, `input`, `textarea`,
+            `select`, `button`, `meta`, `link`, `base`, `template`, `noscript`,
+        ] });
+    return dp.sanitize(safe, { ALLOWED_TAGS: SAFE_TAGS, ALLOWED_ATTR: SAFE_ATTRS });
+}
+export const compact_formula = (formula) => formula.replaceAll(/\s+/g, ``);
+// Sanitize a chemical formula with optional subscript formatting
+export const sanitize_formula = (formula, use_subscripts = true) => sanitize_html(format_formula_html(formula, use_subscripts));
+export const sanitize_compact_formula = (formula, use_subscripts = true) => sanitize_formula(compact_formula(formula), use_subscripts);
+const SVG_TEXT_TAGS = [`tspan`, `title`];
+// oxfmt-ignore
+const SVG_TEXT_ATTRS = [`dx`, `dy`, `x`, `y`, `fill`, `font-size`, `font-weight`, `baseline-shift`];
+// Sanitize HTML intended for SVG text contexts (tspan, title)
+export const sanitize_svg = (html) => sanitize_svg_content(html, SVG_TEXT_TAGS, SVG_TEXT_ATTRS);
+// oxfmt-ignore
+const SVG_ICON_TAGS = [
+    `path`, `circle`, `rect`, `line`, `polyline`, `polygon`, `g`, `ellipse`,
+    `clipPath`, `defs`, `mask`, `use`, `title`,
+];
+// oxfmt-ignore
+const SVG_ICON_ATTRS = [
+    `d`, `fill`, `stroke`, `stroke-width`, `stroke-linecap`, `stroke-linejoin`,
+    `cx`, `cy`, `r`, `rx`, `ry`, `x`, `y`, `x1`, `y1`, `x2`, `y2`,
+    `width`, `height`, `viewBox`, `points`, `transform`, `opacity`,
+    `clip-path`, `clip-rule`, `fill-rule`, `id`, `class`,
+];
+// Sanitize inline SVG markup (path, circle, rect, etc.) for icon rendering
+export const sanitize_icon_svg = (html) => sanitize_svg_content(html, SVG_ICON_TAGS, SVG_ICON_ATTRS);

package/dist/settings.d.ts

@@ -0,0 +1,319 @@
+import type { ColorScaleType, D3InterpolateName } from './colors';
+import type { HullFaceColorMode } from './convex-hull/types';
+import type { D3SymbolName } from './labels';
+import type { Vec3 } from './math';
+import type { BandwidthOption, Orientation, SankeyNodeAlign, SankeyOrientation, SunburstLabelRotation, SunburstLabelText, SunburstShape, SunburstValueMode, ViolinKind, ViolinSide, WhiskerMode } from './plot';
+import type { BondingStrategy } from './structure/bonding';
+export interface SettingType<T = unknown> {
+    value: T;
+    description: string;
+    enum?: Readonly<Record<Extract<T, string>, string>>;
+    minimum?: number;
+    maximum?: number;
+    minItems?: number;
+    maxItems?: number;
+    context?: `web` | `editor` | `notebook` | `all`;
+}
+export declare const SHOW_BONDS_OPTIONS: readonly ["never", "always", "crystals", "molecules"];
+export type ShowBonds = (typeof SHOW_BONDS_OPTIONS)[number];
+export type CameraProjection = `perspective` | `orthographic`;
+export declare const VECTOR_COLOR_MODES: readonly ["auto", "element", "spin_direction", "magnitude", "uniform"];
+export type VectorColorMode = (typeof VECTOR_COLOR_MODES)[number];
+export type VectorLayerConfig = {
+    visible: boolean;
+    color: string | null;
+    scale: number | null;
+};
+export declare const ATOM_COLOR_MODE_OPTIONS: readonly ["element", "coordination", "wyckoff", "custom"];
+export type AtomColorMode = (typeof ATOM_COLOR_MODE_OPTIONS)[number];
+type DisplayConfigType = {
+    x_grid: SettingType<boolean>;
+    y_grid: SettingType<boolean>;
+    y2_grid: SettingType<boolean>;
+    x_zero_line: SettingType<boolean>;
+    y_zero_line: SettingType<boolean>;
+};
+type BarStyleType = {
+    color: SettingType<string>;
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+    stroke_color: SettingType<string>;
+    stroke_opacity: SettingType<number>;
+};
+type PointStyleType = {
+    size: SettingType<number>;
+    color: SettingType<string>;
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+    stroke_color: SettingType<string>;
+    stroke_opacity: SettingType<number>;
+};
+type LineStyleType = {
+    width: SettingType<number>;
+    color: SettingType<string>;
+    opacity: SettingType<number>;
+    dash: SettingType<string>;
+};
+type SimpleBarStyleType = {
+    color: SettingType<string>;
+    opacity: SettingType<number>;
+    border_radius: SettingType<number>;
+};
+type SimpleLineStyleType = {
+    width: SettingType<number>;
+    color: SettingType<string>;
+};
+type BoxStyleType = {
+    color: SettingType<string>;
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+    stroke_color: SettingType<string>;
+    border_radius: SettingType<number>;
+};
+type BoxWhiskerStyleType = {
+    width: SettingType<number>;
+    color: SettingType<string>;
+    cap_fraction: SettingType<number>;
+};
+type BoxLineStyleType = {
+    width: SettingType<number>;
+    color: SettingType<string>;
+};
+type BoxOutlierStyleType = {
+    radius: SettingType<number>;
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+};
+type BoxViolinStyleType = {
+    opacity: SettingType<number>;
+    stroke_width: SettingType<number>;
+};
+type ConvexHullCommonType = {
+    camera_zoom: SettingType<number>;
+    camera_center_x: SettingType<number>;
+    camera_center_y: SettingType<number>;
+    color_mode: SettingType<`stability` | `energy`>;
+    color_scale: SettingType<string>;
+    show_stable: SettingType<boolean>;
+    show_unstable: SettingType<boolean>;
+    show_stable_labels: SettingType<boolean>;
+    show_unstable_labels: SettingType<boolean>;
+    max_hull_dist_show_phases: SettingType<number>;
+    max_hull_dist_show_labels: SettingType<number>;
+    fullscreen: SettingType<boolean>;
+    info_pane_open: SettingType<boolean>;
+    legend_pane_open: SettingType<boolean>;
+};
+type ConvexHullWith3DType = ConvexHullCommonType & {
+    show_hull_faces: SettingType<boolean>;
+    hull_face_color: SettingType<string>;
+    hull_face_opacity: SettingType<number>;
+    hull_face_color_mode: SettingType<HullFaceColorMode>;
+};
+export interface SettingsConfig {
+    color_scheme: SettingType<string>;
+    background_color: SettingType<string>;
+    background_opacity: SettingType<number>;
+    symmetry: {
+        symprec: SettingType<number>;
+        algo: SettingType<`Moyo` | `Spglib`>;
+    };
+    structure: {
+        atom_radius: SettingType<number>;
+        same_size_atoms: SettingType<boolean>;
+        show_atoms: SettingType<boolean>;
+        show_image_atoms: SettingType<boolean>;
+        sphere_segments: SettingType<number>;
+        bond_thickness: SettingType<number>;
+        auto_bond_order: SettingType<boolean>;
+        aromatic_display: SettingType<`aromatic` | `kekule`>;
+        show_bonds: SettingType<ShowBonds>;
+        bond_color: SettingType<string>;
+        bonding_strategy: SettingType<BondingStrategy>;
+        atom_color_mode: SettingType<AtomColorMode>;
+        atom_color_scale: SettingType<D3InterpolateName>;
+        atom_color_scale_type: SettingType<ColorScaleType>;
+        show_gizmo: SettingType<boolean>;
+        camera_position: SettingType<Vec3>;
+        camera_projection: SettingType<CameraProjection>;
+        initial_zoom: SettingType<number>;
+        fov: SettingType<number>;
+        rotation_damping: SettingType<number>;
+        rotate_speed: SettingType<number>;
+        zoom_speed: SettingType<number>;
+        pan_speed: SettingType<number>;
+        zoom_to_cursor: SettingType<boolean>;
+        max_zoom: SettingType<number | undefined>;
+        min_zoom: SettingType<number | undefined>;
+        auto_rotate: SettingType<number>;
+        rotation: SettingType<Vec3>;
+        show_site_labels: SettingType<boolean>;
+        show_site_indices: SettingType<boolean>;
+        site_label_size: SettingType<number>;
+        site_label_color: SettingType<string>;
+        site_label_bg_color: SettingType<string>;
+        site_label_padding: SettingType<number>;
+        site_label_offset: SettingType<Vec3>;
+        ambient_light: SettingType<number>;
+        directional_light: SettingType<number>;
+        vector_configs: SettingType<Record<string, VectorLayerConfig>>;
+        vector_scale: SettingType<number>;
+        vector_color: SettingType<string>;
+        vector_color_mode: SettingType<VectorColorMode>;
+        vector_color_scale: SettingType<D3InterpolateName>;
+        vector_normalize: SettingType<boolean>;
+        vector_uniform_thickness: SettingType<boolean>;
+        vector_origin_gap: SettingType<number>;
+        vector_shaft_radius: SettingType<number>;
+        vector_arrow_head_radius: SettingType<number>;
+        vector_arrow_head_length: SettingType<number>;
+        show_cell: SettingType<boolean>;
+        show_cell_vectors: SettingType<boolean>;
+        cell_edge_opacity: SettingType<number>;
+        cell_surface_opacity: SettingType<number>;
+        cell_edge_color: SettingType<string>;
+        cell_surface_color: SettingType<string>;
+        cell_edge_width: SettingType<number>;
+        fullscreen_toggle: SettingType<boolean>;
+    };
+    trajectory: {
+        auto_play: SettingType<boolean>;
+        fps: SettingType<number>;
+        fps_range: SettingType<[number, number]>;
+        display_mode: SettingType<`structure+scatter` | `structure` | `scatter` | `histogram` | `structure+histogram`>;
+        show_controls: SettingType<boolean>;
+        fullscreen_toggle: SettingType<boolean>;
+        step_labels: SettingType<number>;
+        layout: SettingType<`auto` | Orientation>;
+        allow_file_drop: SettingType<boolean>;
+        bin_file_threshold: SettingType<number>;
+        text_file_threshold: SettingType<number>;
+        use_indexing: SettingType<boolean>;
+        chunk_size: SettingType<number>;
+        step_label_format: SettingType<string>;
+        property_value_format: SettingType<string>;
+        tooltip_format: SettingType<string>;
+        enable_keyboard_shortcuts: SettingType<boolean>;
+        show_parsing_progress: SettingType<boolean>;
+        compact_controls: SettingType<boolean>;
+        show_filename_in_controls: SettingType<boolean>;
+        smooth_playback: SettingType<boolean>;
+        loop_playback: SettingType<boolean>;
+        pause_on_hover: SettingType<boolean>;
+        highlight_current_frame: SettingType<boolean>;
+        show_frame_info: SettingType<boolean>;
+        max_frames_in_memory: SettingType<number>;
+        memory_usage_warning_threshold: SettingType<number>;
+        enable_performance_monitoring: SettingType<boolean>;
+        prefetch_frames: SettingType<number>;
+        cache_parsed_data: SettingType<boolean>;
+    };
+    plot: {
+        animation_duration: SettingType<number>;
+        enable_zoom: SettingType<boolean>;
+        zoom_factor: SettingType<number>;
+        auto_fit_range: SettingType<boolean>;
+        grid_lines: SettingType<boolean>;
+        axis_labels: SettingType<boolean>;
+        show_x_zero_line: SettingType<boolean>;
+        show_y_zero_line: SettingType<boolean>;
+        show_x_grid: SettingType<boolean>;
+        show_x2_grid: SettingType<boolean>;
+        show_y_grid: SettingType<boolean>;
+        show_y2_grid: SettingType<boolean>;
+        x_format: SettingType<string>;
+        x2_format: SettingType<string>;
+        y_format: SettingType<string>;
+        y2_format: SettingType<string>;
+        x_scale_type: SettingType<string>;
+        y_scale_type: SettingType<string>;
+        x_ticks: SettingType<number>;
+        y_ticks: SettingType<number>;
+    };
+    scatter: {
+        show_legend: SettingType<boolean>;
+        show_points: SettingType<boolean>;
+        show_lines: SettingType<boolean>;
+        symbol_type: SettingType<D3SymbolName>;
+        display: DisplayConfigType;
+        point: PointStyleType;
+        line: LineStyleType;
+    };
+    histogram: {
+        mode: SettingType<`overlay` | `single`>;
+        show_legend: SettingType<boolean>;
+        bin_count: SettingType<number>;
+        bar: BarStyleType;
+        display: DisplayConfigType;
+    };
+    bar: {
+        display: DisplayConfigType;
+        bar: SimpleBarStyleType;
+        line: SimpleLineStyleType;
+    };
+    box: {
+        whisker_mode: SettingType<WhiskerMode>;
+        box_width: SettingType<number>;
+        show_outliers: SettingType<boolean>;
+        show_mean: SettingType<boolean>;
+        kind: SettingType<ViolinKind>;
+        side: SettingType<ViolinSide>;
+        bandwidth: SettingType<Exclude<BandwidthOption, number>>;
+        violin_width: SettingType<number>;
+        violin_box_width: SettingType<number>;
+        box: BoxStyleType;
+        whisker: BoxWhiskerStyleType;
+        median: BoxLineStyleType;
+        outlier: BoxOutlierStyleType;
+        violin: BoxViolinStyleType;
+        display: DisplayConfigType;
+    };
+    sankey: {
+        orientation: SettingType<SankeyOrientation>;
+        node_align: SettingType<SankeyNodeAlign>;
+        node_width: SettingType<number>;
+        node_padding: SettingType<number>;
+        link_opacity: SettingType<number>;
+        show_node_labels: SettingType<boolean>;
+        iterations: SettingType<number>;
+    };
+    sunburst: {
+        shape: SettingType<SunburstShape>;
+        value_mode: SettingType<SunburstValueMode>;
+        max_depth: SettingType<number>;
+        inner_radius: SettingType<number>;
+        pad_angle: SettingType<number>;
+        min_fraction: SettingType<number>;
+        show_labels: SettingType<boolean>;
+        label_rotation: SettingType<SunburstLabelRotation>;
+        label_text: SettingType<SunburstLabelText>;
+        zoom_on_click: SettingType<boolean>;
+        show_breadcrumbs: SettingType<boolean>;
+    };
+    composition: {
+        display_mode: SettingType<`pie` | `bubble` | `bar`>;
+        color_scheme: SettingType<string>;
+    };
+    convex_hull: {
+        binary: ConvexHullCommonType;
+        ternary: ConvexHullWith3DType & {
+            camera_elevation: SettingType<number>;
+            camera_azimuth: SettingType<number>;
+        };
+        quaternary: ConvexHullWith3DType & {
+            camera_rotation_x: SettingType<number>;
+            camera_rotation_y: SettingType<number>;
+        };
+    };
+}
+export declare const SETTINGS_CONFIG: SettingsConfig;
+export type DefaultSettings = {
+    [K in keyof SettingsConfig]: SettingsConfig[K] extends SettingType<infer T> ? T : SettingsConfig[K] extends Record<string, unknown> ? {
+        [NK in keyof SettingsConfig[K]]: SettingsConfig[K][NK] extends SettingType<infer T> ? T : SettingsConfig[K][NK] extends Record<string, unknown> ? {
+            [NNK in keyof SettingsConfig[K][NK]]: SettingsConfig[K][NK][NNK] extends SettingType<infer T> ? T : never;
+        } : never;
+    } : never;
+};
+export declare const DEFAULTS: DefaultSettings;
+export declare const merge: (user?: Partial<DefaultSettings>) => DefaultSettings;
+export {};