tiny.css.cascade

1/// A computed style: one value per property, dense and indexed by identifier.2pub const Computed = struct {3    values: [property.count]Value = @splat(.{}),45    pub fn get(self: *const Computed, id: property.Id) Value {6        std.debug.assert(id != .invalid);7        return self.values[@backingInt(id)];8    }910    pub fn set(self: *Computed, id: property.Id, item: Value) void {11        std.debug.assert(id != .invalid);12        self.values[@backingInt(id)] = item;13    }1415    /// The computed style of an element with no declarations and no parent.16    pub fn initial() Computed {17        var result = Computed{};18        for (property.entries, 1..) |entry, index| result.values[index] = entry.initial;19        return result;20    }21};

1/// One custom property declaration. Its value stays raw text, because a custom2/// property's value is a token sequence rather than a typed value.3pub const Custom = struct {4    name: u32,5    start: u32,6    end: u32,7    important: bool = false,8};

1/// One custom property's winning declaration.2pub const CustomSlot = struct {3    name: u32 = 0,4    start: u32 = 0,5    end: u32 = 0,6    level: Level = .user_agent_normal,7    specificity: Specificity = .{},8    order: u32 = 0,9    inherited: bool = false,10};

1/// The custom properties in scope for one element. Overflow rejects the extra2/// declaration and counts it rather than evicting a resolved one.3pub const CustomTable = struct {4    slots: [max_custom_properties]CustomSlot = @splat(.{}),5    count: u32 = 0,6    rejected: u32 = 0,78    pub fn find(self: *const CustomTable, name: u32) ?usize {9        var index: usize = 0;10        while (index < self.count) : (index += 1) {11            if (self.slots[index].name == name) return index;12        }13        return null;14    }1516    fn clear(self: *CustomTable) void {17        self.count = 0;18        self.rejected = 0;19    }20};

1/// The cascade levels in increasing precedence. Importance inverts the origin2/// order, which is the whole reason the levels are named rather than derived.3pub const Level = enum(u8) {4    user_agent_normal = 0,5    user_normal = 1,6    author_normal = 2,7    author_important = 3,8    user_important = 4,9    user_agent_important = 5,10};

1/// The three cascade origins this engine carries.2pub const Origin = enum(u8) {3    user_agent = 0,4    user = 1,5    author = 2,6};

1/// Resolves one element's cascade. The caller owns it and reuses it across2/// elements, so the cascade allocates nothing.3///4/// A substituted string value borrows the resolver's substitution buffer and5/// stays valid until the next `begin`.6pub const Resolver = struct {7    slots: [property.count][level_count]Slot = @splat(@splat(.{})),8    customs: CustomTable = .{},9    buffer: [max_substitution_bytes]u8 = undefined,10    names: ?*const atom.Table = null,11    used: u32 = 0,12    source: []const u8 = &.{},13    substitution_rejected: u32 = 0,1415    /// Starts a fresh element. `parent_customs` seeds the inherited custom16    /// properties, which is how a custom property reaches a subtree.17    pub fn begin(18        self: *Resolver,19        source: []const u8,20        names: ?*const atom.Table,21        parent_customs: ?*const CustomTable,22    ) void {23        self.slots = @splat(@splat(.{}));24        self.names = names;25        self.customs.clear();26        self.used = 0;27        self.source = source;28        self.substitution_rejected = 0;29        if (parent_customs) |table| {30            var index: usize = 0;31            while (index < table.count and index < max_custom_properties) : (index += 1) {32                self.customs.slots[index] = table.slots[index];33                self.customs.slots[index].inherited = true;34            }35            self.customs.count = @intCast(index);36        }37    }3839    /// Offers one declaration to the cascade.40    pub fn add(41        self: *Resolver,42        declaration: value.Declaration,43        origin: Origin,44        specificity: Specificity,45        order: u32,46    ) void {47        const id: property.Id = @fromBackingInt(@intCast(declaration.property));48        if (id == .invalid) return;49        const level = levelOf(origin, declaration.important());50        const slot = &self.slots[declaration.property][@backingInt(level)];51        const candidate = Slot{52            .value = declaration.value(),53            .specificity = specificity,54            .order = order,55            .present = true,56        };57        if (!slot.present or wins(candidate, slot.*)) slot.* = candidate;58    }5960    /// Offers one custom property declaration to the cascade.61    pub fn addCustom(62        self: *Resolver,63        custom: Custom,64        origin: Origin,65        specificity: Specificity,66        order: u32,67    ) void {68        const level = levelOf(origin, custom.important);69        const candidate = CustomSlot{70            .name = custom.name,71            .start = custom.start,72            .end = custom.end,73            .level = level,74            .specificity = specificity,75            .order = order,76        };77        if (self.customs.find(custom.name)) |index| {78            const existing = self.customs.slots[index];79            if (existing.inherited or customWins(candidate, existing)) {80                self.customs.slots[index] = candidate;81            }82            return;83        }84        if (self.customs.count == max_custom_properties) {85            self.customs.rejected += 1;86            return;87        }88        self.customs.slots[self.customs.count] = candidate;89        self.customs.count += 1;90    }9192    /// Resolves every property against `parent` and writes the computed style.93    pub fn finish(self: *Resolver, parent: ?*const Computed, out: *Computed) void {94        out.values[0] = .{};95        for (property.entries, 1..) |entry, index| {96            const id: property.Id = @fromBackingInt(@intCast(index));97            const from_parent = if (parent) |source| source.get(id) else entry.initial;98            const winner = self.resolve(index);99            out.values[index] = self.compute(id, winner, entry, from_parent);100        }101    }102103    fn compute(104        self: *Resolver,105        id: property.Id,106        winner: ?Slot,107        entry: property.Metadata,108        from_parent: Value,109    ) Value {110        const fallback = if (entry.inherited) from_parent else entry.initial;111        const slot = winner orelse return fallback;112        const resolved = if (slot.value.flags & flag_pending != 0)113            self.substituted(id, slot.value) orelse return fallback114        else115            slot.value;116        return switch (resolved.asKeyword()) {117            .inherit => from_parent,118            .initial, .revert => entry.initial,119            .unset => fallback,120            else => resolved,121        };122    }123124    fn resolve(self: *Resolver, index: usize) ?Slot {125        var excluded: u8 = 0;126        var round: u32 = 0;127        while (round <= 3) : (round += 1) {128            const found = self.pick(index, excluded) orelse return null;129            if (found.slot.value.asKeyword() != .revert) return found.slot;130            const origin = originOf(found.level);131            excluded |= originBit(origin);132        }133        return null;134    }135136    const Winner = struct {137        slot: Slot,138        level: Level,139    };140141    fn pick(self: *Resolver, index: usize, excluded: u8) ?Winner {142        var level: usize = level_count;143        while (level > 0) {144            level -= 1;145            const candidate: Level = @fromBackingInt(@intCast(level));146            if (excluded & originBit(originOf(candidate)) != 0) continue;147            const slot = self.slots[index][level];148            if (slot.present) return .{ .slot = slot, .level = candidate };149        }150        return null;151    }152153    fn substituted(self: *Resolver, id: property.Id, pending: Value) ?Value {154        const begin_offset = self.used;155        var visiting: u64 = 0;156        if (!self.expandSpan(pending.a, pending.a + pending.b, 0, &visiting)) {157            self.used = begin_offset;158            self.substitution_rejected += 1;159            return null;160        }161        const text = self.buffer[begin_offset..self.used];162        const grammar = property.metadata(id).grammar;163        const parsed = value.parse(grammar, text, 0, @intCast(text.len));164        if (!parsed.present()) return null;165        return parsed;166    }167168    fn expandSpan(self: *Resolver, start: u32, end: u32, depth: u32, visiting: *u64) bool {169        if (depth > max_substitution_depth) return false;170        std.debug.assert(end <= self.source.len);171        var tokenizer = token.Tokenizer{ .source = self.source[0..end], .index = start };172        var copied = start;173        var guard: usize = 0;174        while (guard <= self.source.len + 1) : (guard += 1) {175            const next = tokenizer.next();176            if (next.kind == .eof) break;177            if (next.kind != .function) continue;178            if (!std.ascii.eqlIgnoreCase(next.value(self.source), "var")) continue;179            const close = closeParen(&tokenizer, self.source.len) orelse return false;180            if (!self.write(self.source[copied..next.start])) return false;181            if (!self.expandVariable(next.end, close, depth, visiting)) return false;182            copied = close + 1;183            tokenizer.index = close + 1;184        }185        return self.write(self.source[copied..end]);186    }187188    fn expandVariable(self: *Resolver, start: u32, end: u32, depth: u32, visiting: *u64) bool {189        const body = self.source[start..end];190        const comma = topLevelComma(body);191        const name = std.mem.trim(u8, body[0 .. comma orelse body.len], " \t\r\n\x0C");192        if (!property.isCustom(name)) return false;193        if (self.lookupCustom(name)) |index| {194            const mask = @as(u64, 1) << @intCast(index);195            if (visiting.* & mask != 0) return false;196            visiting.* |= mask;197            const slot = self.customs.slots[index];198            const expanded = self.expandSpan(slot.start, slot.end, depth + 1, visiting);199            visiting.* &= ~mask;200            if (expanded) return true;201        }202        const offset = comma orelse return false;203        const fallback_start = start + @as(u32, @intCast(offset)) + 1;204        return self.expandSpan(fallback_start, end, depth + 1, visiting);205    }206207    fn lookupCustom(self: *const Resolver, name: []const u8) ?usize {208        const table = self.names orelse return null;209        const id = table.lookup(name);210        if (id == atom.none) return null;211        if (self.customs.count > max_custom_properties) return null;212        return self.customs.find(id);213    }214215    fn write(self: *Resolver, text: []const u8) bool {216        if (self.used + text.len > self.buffer.len) return false;217        @memcpy(self.buffer[self.used..][0..text.len], text);218        self.used += @intCast(text.len);219        return true;220    }221};

1/// The winning declaration at one cascade level.2pub const Slot = struct {3    value: Value = .{},4    specificity: Specificity = .{},5    order: u32 = 0,6    present: bool = false,7};

1/// Bit one of a value's flag word marks a declaration whose text still holds a2/// `var()` reference. Its `a` and `b` words are the source span, not a value.3pub const flag_pending: u16 = 2;

1/// The cascade level a declaration lands in.2pub fn levelOf(origin: Origin, important: bool) Level {3    return switch (origin) {4        .user_agent => if (important) .user_agent_important else .user_agent_normal,5        .user => if (important) .user_important else .user_normal,6        .author => if (important) .author_important else .author_normal,7    };8}

1/// The number of cascade levels.2pub const level_count: usize = 6;

1/// The most custom properties one element may carry.2pub const max_custom_properties: usize = 64;

1/// The substitution buffer one element's `var()` expansions share.2pub const max_substitution_bytes: usize = 4096;

1/// The deepest `var()` nesting the resolver expands before failing closed.2pub const max_substitution_depth: u32 = 8;

1/// The origin behind a cascade level.2pub fn originOf(level: Level) Origin {3    return switch (level) {4        .user_agent_normal, .user_agent_important => .user_agent,5        .user_normal, .user_important => .user,6        .author_normal, .author_important => .author,7    };8}

1//! The cascade: origin, importance, specificity, source order, inheritance,2//! the four CSS wide keywords, custom properties, and `var()` substitution.3//!4//! `Resolver` holds one winning declaration per property per cascade level, so5//! `revert` is answered by re-picking with the reverting origin removed rather6//! than by a second pass over the matched rules. The caller owns the resolver7//! and reuses it across elements, so the cascade allocates nothing.8//!9//! A computed style is a dense array indexed by property identifier, which is10//! what makes inheritance a copy and comparison a memcmp.1112const resolve = @import("resolve.zig");1314pub const Computed = resolve.Computed;15pub const Custom = resolve.Custom;16pub const CustomSlot = resolve.CustomSlot;17pub const CustomTable = resolve.CustomTable;18pub const Level = resolve.Level;19pub const Origin = resolve.Origin;20pub const Resolver = resolve.Resolver;21pub const Slot = resolve.Slot;22pub const flag_pending = resolve.flag_pending;23pub const level_count = resolve.level_count;24pub const levelOf = resolve.levelOf;25pub const max_custom_properties = resolve.max_custom_properties;26pub const max_substitution_bytes = resolve.max_substitution_bytes;27pub const max_substitution_depth = resolve.max_substitution_depth;28pub const originOf = resolve.originOf;

1pub const cascade = @import("cascade/root.zig");